Best Practices For APIs: Consuming (2)
About These Documents
This document is 2 of 3 which describe best practices for consuming APIs provided by others.
Risk Management
When relying on an externally hosted service there can be some element of risk such as loss of service, change in price of a service or performance problems. Some providers may feel the need to change APIs or feeds without notice which may mean that your applications functionality becomes deprecated. This should not stop developers from using these providers but means that you should be cautious and consider providing alternatives for when a service is not (or no longer) available. Developers using external APIs should consider all eventualities and be prepared for change. One approach may be to document a risk management strategy [1] and have a redundancy solution in mind. Another might be to avoid using unstable APIs in mission critical services: bear in mind the organisational embedding of services. Developing a good working relationship with the API supplier wherever possible will allow you to keep a close eye on the current situation and the likelihood of any change.
Provide Documentation
When using an external API it is important to document your processes. Note the resources you have used to assist you, dependencies and workarounds and detail all instructions. Record any strange behaviour or side effects. Ensure you document the version of API your service/application was written for.
Bench mark the APIs you use in order to determine the level of service you can expect to get out of them.
Share Resources and Experiences
It could be argued that open APIs work because people share. Feeding back things you learn to the development community should be a usual step in the development process.
APIs providers benefit from knowing who use their APIs and how they use them. You should make efforts provide clear, constructive and relevant feedback on the code through bug reports), usability and use of APIs you engage with. If it is open source code it should be fairly straightforward to improve an API to meet your needs and in doing so offer options to other users. If you come across a difficulty that the documentation failed to solve then either update the documentation, contact the provider or blog about your findings (and tell the provider). Publish success stories and provide workshops to showcase what has and can been achieved. Sharing means that you can save others time. The benefits are reciprocal. As one developed commented:
"If you find an interesting or unexpected use of a method, or a common basic use which isn't shown as an example already, comment on its documentation page. If you find that a method doesn't work where it seems that it should, comment on its documentation page. If you are confused by documentation but then figure out the intended or correct meaning, comment on its documentation page."
Sharing should also be encouraged internally. Ensure that all the necessary teams in your institution know which APIs are relevant to what services, and that the communications channels are well used. Developers should be keeping an eye on emerging practice; what's 'cool' etc. Share this with your team.
Feedback how and why you are using the API, often service providers are in the dark about who is using their service and why, and being heard can help guide the service to where you need it to be, as well as re-igniting developer interest in pushing on the APIs.
Respect
When using someone else's software it is important to respect the terms of use. This may mean making efforts to minimise load on the API providers servers or limiting the number of calls made to the service (e.g. by using a local cache or returned data, only refreshed once a given time period has expired). Using restricted examples while developing and testing is a good way to avoid overload the provider's server. There may also be sensitivity or IPR issues relating to data shared.
Note that caching introduces technical issues. Latency or stale data could be a problem if there is caching.
Acknowledgements
This document is based on advice provided by UKOLN's Good APIs project. Further information is available at <http://blogs.ukoln.ac.uk/good-apis-jisc/>.
References
- Using the Risks and Opportunities Framework, UKOLN briefing document no. 68, <http://www.ukoln.ac.uk/cultural-heritage/documents/briefing-68/>
About The Best Practices For APIs Documents
The Best Practices For APIs series of briefing documents have been published for the cultural heritage sector. The advice provided in the documents is based on resources gathered by UKOLN for the JISC-funded Good APIs project.
Further information on the Good APIs project is available from the project's blog at <http://blogs.ukoln.ac.uk/good-apis-jisc/>.
