Guest Contribution by Claire Jane Ward
Those in the business of designing APIs for a web environment often have their own opinions about the right way to go about this, as well as habits they have formed over time which may help or hinder their efforts.
If you are a relative newcomer, it is useful to establish a framework within which you can orchestrate and organize your API designing going forwards. This list of tutorials is a good starting point if you’d like to create your own, but it is also worth learning about the best practices to adhere to so that you do not succumb to common pitfalls.
Clarity is important to effective implementation
It is safe to assume that the web API you create will not exist in a vacuum and only be harnessed and maintained by you, but will also need to be shared and understood by others using live chat tools. This is generally a collaborative process and as such it pays to make sure that your methodology is clear, logical and accessible to a variety of team members.
The other advantage of creating a concise, unambiguous approach to web API design as early as possible is that you can make adjustments as you progress, enhancing how it functions, while also ensuring that this does not conflict with changes that might be necessary in terms of the implementation details. In short, being able to alter the design pipeline while still being agile in terms of target platforms and even user interface elements will work in your favor.
Start with a list
Before diving in headfirst, take the time to outline the different types of data that might be called upon by an app which makes use of your web API.
The nature of these will depend on the function that the app is intended to fulfill; in a calendar app designed for personal organization, for example, this could include descriptions of the different types of alerts that will be covered.
Reading up on semantic descriptors and how they operate in the context of web APIs will help you make more effective use of them at this early stage.
Map everything out
Your web API will inhabit various states as part of its normal operation, but to achieve this without creating conflicts you need to create a definitive diagram that maps the transitions between each of these states.
This diagram can be uncluttered at first, as it is not necessary to single out protocol methods involved in the transitions until you are further along with this process. The idea here is to let you work out whether there are any missing links, or whether your planned configuration is good to go.
Find a format that works for you
Web APIs can harness a variety of standardized solutions for sending and receiving data, including HTML and XMPP.
Your choice will again be unique to the needs of your project; do you need a super lightweight format, or does your API’s function necessitate something that is more robust in terms of its feature set?
Most of all, remember to scrutinize your processes regularly and seek input from others to get the best results.
Stick with status codes that avoid confusion
When working on an API it is best to ensure that error details are easily identifiable within status codes, as if there is even the smallest degree of ambiguity at this point, you will not only make life harder for yourself, but could also compromise the trust built with users.
Consistency across status codes will also be advantageous further down the line when other developers enter the fray, since while you may remember whatever arcane reasons inspired your original choices, a third party who is coming in blind will not, so think of them first.
Ultimately this should make your web API straightforward to work with, rather than feeling like something that needs to be battled against. The less time it takes to master, the more attractive it will be.
Select nouns sensibly
Remember that it is not just developers that will be working with your web API, but also end users who will have a very different experience level and skill set at their disposal. For this reason, the nouns you settle on should be sufficiently precise so as to be practical and functional to anyone who encounters them.
The issue of whether to choose singular or plural nouns is up for debate, although in general it is always worth choosing one approach and sticking with it, rather than flip-flopping from one URL to the next. Pluralizing nouns is certainly helpful in some circumstances, especially if a collection is being described within the API.
There are ample other things to learn about web API design, but the most effective method for finding them out is actually getting stuck in with the development process yourself.