November 4, 2016

An API is an interface that a developer exposes to the world via a link and that provides data manipulation methods. Usually, we refer to an API service as an endpoint.

What is the use of an API?

An API is used mostly when you need to make some data public or you need to store it inside a datastore, such as a database. There are many applications that expose some of their data to other developers for them to use in their own applications, for example, we have social networks that offer us information about a user’s profile and activity based on their authentication data, through an API. That is why login via Facebook is possible.

Furthermore, we can build an API the other way around: letting other applications or services to send data, process and store it remotely in your datastore. As an example, we have Google Drive, Dropbox, Evernote and WordPress that have the possibility to receive information from third parties and store them for further access from their portals.

What are the main rules in designing a solid API?

1. Consider not creating an API at all!

Most of the times, developers build APIs in situations that don’t require it. Let’s remember the utility of such services: giving access and/or storing remote data. So, next time the client asks for an application that manages internal corporate information, remember that you really don’t need to create any API functionality.

2. Analyze the context of use

After you have clearly decided that you need to create an endpoint, sketch up some use cases for it. Who makes the requests? What are the expected responses? What type of data is exchanged? After that, take a look at the overall results and decide whether the service should be REST or SOAP, decide what level of security is required and profile the physical resource usage.

It is very important to have a pristine image over the API’s usage in terms of number of concurrent requests so that it can run smoothly and is easier to maintain and scale.

Don’t neglect the security in your end-to-end communication.

3. Make it exception-free

An endpoint is harder to manage than your normal web, mobile or desktop application. Usually, once you deploy it, it should run uninterrupted until the next major update of its functionality. That is why you, as a developer, need to take extra care to eliminate any source of possible unexpected termination.

Remember to stress-test your service and try to cover as much code with unit tests. Depending on the situation, run as many concurrent requests as expected (and even add 100 more : ) )

4. Make it scalable

Make sure that your service can scale up in the future. Say, right now, you have 100 users, so one machine is probably enough, but what if your app goes viral and you end up having thousands of users overnight? The instant reaction would be optimizing the existent code, but you will soon find out that is not enough. Okay, you go buy more rackspace, more computing power, but how well does your endpoint benefit from clustering?

Think big, it helps!

5. Documentation is important!

Chances are the code you write will outlive the period of time you are an employee of the company, so make sure you leave something behind for the (un)lucky dev who has to maintain it.

You would appreciate if it happened to you, right?

6. Does the third-party data storage solution hold?

Sometimes a plain MySql instance on one server isn’t enough to provide optimum results for your API. Make sure that whatever solution you choose, it is configured properly and is able to keep up with the scaling factor. There is no reason to optimize the code without making sure that the DB can hold and manage the amount of data ingested.

Give NoSql a try, it is worth it!

7. Never add business logic in your endpoint

This is a common mistake developers make in designing a data access WS. The reason is simple: if this service is called when some statistical data is needed, why preprocess it, when it is much easier to process it on demand?

Well, first of all, it defeats the sole purpose of the endpoint itself. Second, let’s think about the communication between our applications’ modules: we have the Model, which represents the data, we have the View, which shows it to the user and the Controller which binds the two. Why mix the data manipulation role with the business logic?

8. Clean code, ladies and gents!

Use it every time you touch the keys on your keyboard.

Ending notes

When you are placed in front of a decision of whether or not to build an API and you decide that it’s the way to go, take care of the design process before even importing that Apache library that you always use or that DB connector that you never remember how to insert a date into!


Vlad Butnaru

This article is proudly written by our dear colleague Vlad Butnaru, Java Developer at Feel IT Services
Back to top