Nowadays almost all successful products include an api to allow for integration and extension, with many products actually being the api. Products like Trello are completely api driven, with their own UI being built with the same api as you can use. The benefits to this approach start to pay for themselves as the product grows along with your customer base.

Designing a good api

A good api should reflect your business domain model through well designed restful endpoints. For many developers not experienced in api design there will be a tendency to follow more of an RPC style interface similar to something you would expose in a DLL type library. This approach will be quick but should be avoided at all costs.

You should think about your domain model in terms of resources and how they change. If you want to create an account, an internal module may have a function like createAccount(userName) however your api endpoint would look more like

POST /accounts {name:bob}

Now to change the account name you are updating a property on the account resource

PUT /accounts/{acid} {name:bob}

This is all pretty easy to understand however it starts to get more complicated when you need run a process like send customer receipt or send confirmation email. The lazy approach would be to add an endpoint such as

POST /accounts/accountId/sendCustomerReceipt

This should feel wrong and it is.

The key to designing a good api is understanding the domain that your building for. Domain driven design principles will help you understand your model and how interactions should occur. When you look at the api documentation you should be able to understand what is happening from the endpoints and resources

Documentation

Even if your api is for internal use, it’s worth documenting it from the start. There are a number of solutions available for documenting apis however I’ve found Swagger to be one of the best (at least when used in a node environment)

Security is essential

By it’s very nature your api is going to be exposed and vunerable to all kinds of misuse so before you start it’s essential you understand how you are going protect access and usage. How will you authenticate your api and will you need to rate limit the api? Is your api going to be called from a web browser or from a server? Do the resources need user authentication or is a key suitable?

Token based authentication is one of the easiest way to protect your api

Break the rules when you absolutely must

The more you read about restful api design, the more you will encounter the arguments and debates over what constitutes a proper restful api. It’s worth reading the opinions of others on the subject however don’t get too hung up on it, as at the end of the day you need to deliver a product and sometimes you do have to break the rules and create something that will upset the purists.

When it comes to designing api’s there’s a lot of scope for interpretation and each domain is different bringing different challenges. There are a lot of examples of great api’s available to help guide you and a lot of different styles in play. If you’re unsure of how to model a particular domain look at products with similar challenges and see how they work. At the end of the day API design is fun and allows you an exciting opportunity to express your business’s domain. You won’t get it right first time but that’s fine as Version 2 will fix all that