API Integration Basics
APIs can come in all shapes and sizes. However, most successful APIs follow similar patterns in terms of structure, security, data formats, and protocols. Understanding these key aspects can be the difference between a successful API integration and hours of frustration.
Features of an API Integration
While there exists a nearly endless series of options with respect to how to create an API Integration, most webservice APIs will be defined by a handful of key features.
Communication/Protocol
Most typically, a webservice API will be accessible over HTTP. This isn’t a given as technically anything accessible over the Internet may be classed as a “webservice”, however it’s generally a safe assumption. Webservice APIs that use any other strategy are quite rare, outside of the embedded-device space.
Slightly more common is layering a higher-lever protocol on top of HTTP, such as SOAP. While once quite common and still quite relevant in the .Net sphere, this strategy has been gradually losing ground to smaller and lighter APIs that run directly over HTTP
Structure.
The most common approach to structuring a HTTP-based webservice API is called the RESTful paradigm. A significant topic in and of itself, in essence, this approach means that different HTTP Verbs are used to perform different operations. For instance, you might need to use a ‘POST’ request to create something, a ‘PUT’ request to the same URL/endpoint to update it, and a ‘DELETE’ request (again to the same URL) to delete it.
How closely a wbservice follows this approach varies widely. Some keep it formal and expect the integrator to be fluent with their ‘PUTS’ and ‘POSTS’, ‘GETS’ and ‘DELETES’. Others may take a more middle-ground approach and follow a simplified “use ‘GET’ to read, and ‘POST’ to write” pattern. Others may be more laissez-faire about it and take an “all (or most) operations can be performed using both ‘GET’ and ‘POST'”, leaving the integrator free to do whatever is more convenient on their end.
Generally, any pattern is fine, so long as there is one. A quality API will not stipulate arbitrary REST-related requirements with no discernable rhyme or reason.
Response Format
Although APIs have used (and will continue using) a variety of data formats, with public webservice APIs XML and JSON are the dominant players by a wide margin. Although XML was established first and adopted into pretty much everything back in its heyday, it has been rapidly losing ground to the lighter-weight and more human-readable JSON.
Many APIs will allow an integrator to choose whether they want to receive their response in XML or JSON. Where only one format or the other is offered, it’s often possible to judge the age of an API by the data format it returns; XML tends to be preferred by older webservice APIs, and JSON is more common in newer APIs. Some high-level protocols, such as SOAP, may essentially dictate that one format or another be used.
In general, however, if you’re comfortable working with XML and JSON you’ll have no problems talking with most published webservice APIs.
Security
For a modern webservice API integration SSL is the de facto minimum standard when it comes to security. Some APIs may layer additional security on top of this, such as request signing and other cryptographic techniques to verify the origin of the request and guarantee that its contents haven’t been tampered with. For instance, Amazon operates all of their APIs over HTTPS and in addition to that requires API consumers to implement a fairly involved request-signing algorithm.
As a general rule, however, SSL is “secure enough” for an API integration and represents the common starting-point for most webservice APIs. Requiring additional security over and above what SSL offers is somewhat rare, and often costs more in frustration than what it gains in added security.
While increasingly uncommon, it’s not unheard of for a webservice API to operate over plain HTTP with no encryption or other forms of security. This may be okay, but only if the API is neither receiving nor transmitting any personal user data or other sensitive information (including API access/secret keys!). If the API contains any sensitive information, you should not use HTTP!
Other Important Bits
While not part of the API itself, documentation is also of critical importance to an integrator. In the absence of documentation, connecting to an API is all but impossible. Without quality, consistent, up-to-date documentation the task can easily become a frustrating exercise in trial-and-error.
High quality documentation that uses consistent, intuitive terminology to explain concepts and important aspects of an API can be a critical factor in a successful integration. In the event you’re attempting an API integration and you discover that important API documentation is incomprehensible, inaccurate, outdated, or just plain missing, it’s a wonderful opportunity to take a step back and see if maybe there’s an alternative API available that can be used to accomplish the same task.
That’s why here at Doshii, we’ve created a detailed API integration documentation hub, which we constantly keep updated with guides for integrating with our platform. Check it out here
Putting it Together
Success as an integrator depends upon having a good understanding of the defining features of a modern webservice API. A solid knowledge of these basics will help when assessing the relative strengths and weaknesses of different APIs, so that the best candidate can be chosen and wasted time and frustration can be avoided. Combined with quality documentation this should help you quickly develop a clear understanding of
the API and identify any gaps between your own system and the API as early as possible so that any potential issues can be planned for and addressed.
To learn more about integrating with Doshii and to speak with our technical team, get in touch through our contact page.
