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!
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?
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:
```json
{
"links": [
{
"rel": "transactions",
"href": "https://my-api.com/users/:user_id/transactions"
}
]
}
```
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.
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.
Thanks to Andrew Willis for being our guest writer this week and writing a piece on Building an API
If you would like to write a blog for ronaldjamesgroup.com please get in touch!
We are a leading niche digital & tech recruitment specialist for the North East of England. We Specialise in the acquisition of high-performing technology talent across a variety of IT sectors including Digital & Technology Software Development.
Our ultimate goal is to make a positive impact on every client and candidate we serve - from the initial call and introduction, right up to the final delivery, we want our clients and candidates to feel they have had a beneficial and productive experience.
If you’re looking to start your journey in sourcing talent or find your dream job, you’ll need a passionate, motivated team of experts to guide you. Check out our Jobs page for open vacancies. If interested, contact us or call 0191 620 0123 for a quick chat with our team.
Follow us on our blog, Facebook, LinkedIn, Twitter or Instagram to follow industry news, events, success stories and new blogs releases.
Back to Blog
Northumbria House, Samson Close, Killingworth, Newcastle, NE12 6DX
