System integration is often the most challenging aspect of any technical build, both from a development and cost perspective. Joining two systems together requires a solid interface that facilitates good information transfer, not just between your information systems but also between your technical teams.
A SOLID INTERFACE FOR DEVELOPMENT
Getting the right information to support accurate and timely development against an API can be difficult. I’ve listed information that I think is important below. You don’t necessarily need them all, but they will make development progress less troublesome.
Functional review
An important point but one that can often get overlooked before starting, especially in a creative environment. Are the API’s you are consuming fit for the purpose you are intending?
- Can they support the functionality you are trying to offer? You’d be surprised at the number of times I’ve seen application wire-frames signed off that rely on non-existent API functionality….
- Is the API already in production or is it still in development? Working against a moving target could add effort unless a full specification is agreed / known upfront.
- Does the API offer performance and an SLA that is appropriate for your usage. There’s no point building a super fast application that is dependent on a slow and fragile API. You are only as strong as your weakest link.
Documentation
Is the API ‘well-documented’, either online or in a document? Is it recent or is the information out-of-date? Well-documented is subjective but, in my view: in this context it means at least the following:
- Protocol / Language – what is the protocol you should use to communicate with the API (HTTP etc) and what is the data format / language you should use to communicate ( SOAP, REST etc)?
- Endpoints – where does the API live? Are there separate test and live systems? Are the use cases for each system explained? Are the data control policies for each environment explained – this is very important for API’s into communication systems. You don’t want your test system contacting real users. Make sure you know which system should perform the control.
- Authentication – is the API protected? What do you need to do to be able to authenticate with the API (Basic Auth, OAuth etc)
- Methods – is each method in the API explained, including any request parameters and expected responses? Are the expectations on data input (validations) described?
- Error messages – does the documentation explain how the API will notify and provide details of any errors, be that in validation of input or internal more fatal errors?
- Examples – are real code examples available or better yet is there an interactive sandbox, where you can try out example requests and receive mocked responses?
Point of Contact
Is there a point of contact for the API? Do you know where or who to turn to if you need any support whilst developing against or operating against an API? For mature platforms this could be a online documentation and a live ‘status’ page. For line of business API’s this might be ‘the single tech guy in IT’. Either way you’ll need to make sure you know how to get help when you need it.
Almost standard
A lot of the above is now commonplace (thankfully), driven particularly by the standards set by the larger social platforms and the increasing usage of API management platforms (such as Jitterbit) in the enterprise.
I’m sure most developers would agree that developing against an API is often the most interesting type of technical work and developing against a ‘well-documented API’ is also some of the most enjoyable.
