Building an API
Everybody and his dog wants an API these days (Seriously, there’s even a pet-tracker app) so when it comes to building them, it’s always good to know what you’re doing!
Know your API
The first step to building a good API is to know exactly what kind of API you are building.
– What are the API’s use-cases?
– Is the API going to be exclusively available to internal applications or is it going to be a public-facing API?
– What kind of data are you dealing with?
– What methods of authentication (if any) does the API require?
Once you have all the information you require, you can start to plan the API. Some people like to build an API where each endpoint corresponds to a database table, I like to think of endpoints more as services which can provide an interface to create, list, view, update and delete resources, where the resources might be spread over multiple tables. For instance, if you’re creating a user which needs an associated profile, why would you create the user with an API endpoint and create the profile with another?
Simplicity is key
When designing your database structure (hopefully putting a lot of thought into how complex your structure is and how it will scale in the future) I find it best to avoid thinking about the API structure; it’s a separate thing. When it comes to building the API to interact with the database, simplicity is the best way to go. Make the API as painless as possible for the consumer, provide the data they need in a format they can use easily. Provide descriptive resource links, for instance, if your resource is a user which has the ability to log how much money they’ve spent today and where, provide it in the links section:
This will stop your consumer having to do awkward concatenation and make it really easy for them to traverse the API.
Make sure you’re correctly handling errors in the API, catch all Exceptions and deal with them, providing your consumer with enough information for you to be able to check your logs for the issue. Send the right content headers, set the correct status code and make sure that you document the errors too so the person consuming the API knows as much as they can about what went wrong.
Test your endpoints
No matter what language you use, it is absolutely imperative that you write integration tests for the API endpoints, this will help to ensure that the API is working correctly. Remember to test for success and failure, and whenever somebody breaks the API (it will happen..) make sure you write new tests to check that the bug doesn’t get re-introduced in the future.
If the API requires authentication, make sure it is thoroughly documented. Whether you go for basic auth, JWT, Oauth2, a combination of them or something completely different, make sure that using it is as simple as you can and that any token expiry is made apparent to the consumer. Whatever flavour of authentication you decide to go for, make sure it is secure and safe to use.
To wrap it up, this has been a brief, language-agnostic overview of things to think about when building API’s. Remember when you build an API, you are also responsible for the maintenance of the API until the end of time. Even after you die, people are going to swear about it because something doesn’t work 100% correctly for their use-case. There are tons of resources out there which discuss building API’s in great detail, my personal favourite is [Build APIs You Won’t Hate](https://leanpub.com/build-apis-you-wont-hate) by Phil Sturgeon.