API or Application Programming Interface, when I first heard of this term, I thought it to be some form of magical code that helps in fewer bugs and improves quality. However, after exploring, I got to know how deeply I was wrong. API’s that are part of modern mobile and web application allows third-party apps to interact with your application. A well-designed API would help in providing a stable interface that aids to your API’s consumers better understand, improved developer experience,use and integrate with them while helping you maintain it adequately.
But, what exactly means by a Good API? Our post would narrate a few of the best practices for designing an API.
Lets first dive into few of the terminologies[indeed you might be aware] but to be on the same page –
Terminologies
| Resource | The fundamental unit of API.
Resources is an object or a representation of something; it has data and a set of methods associated with it. Example – Company, School, Employees are the resources, while add, update, delete are the method to be performed on this resource. |
| Collections | A set of resources.
Example – a companies is a collection of company resources |
| URL [Uniform Resource Locator] | As the name suggests it is an indication of a path using which the resource could be located and some actions could be performed on it. |
Best Practices of API Design
Describe Resource as Nouns
Resource the fundamental unit of an API, should always be described as a Noun.
For example, we are trying to build an API for Society and Residents.
So, Resources would be, [ Ideally, the resource should always be PLURAL]
Describe HTTP Methods as Verbs and URL’s as sentences
The paths should have the plural form of resources and the HTTP method used should describe the kind of action to be performed on the particular resource.
As URL just talks about the noun, how do we tell the server about the actions that are to be performed on APIs,i.e., update, add or delete?
That’s where HTTP methods come into the picture, have a look at different ways –
| Method | Description |
| GET | Used to recover a representation of a resource. |
| POST | Used to form new resources and sub-resources |
| PUT | Used to update existing resources |
| PATCH | Used to update existing resources |
| DELETE | Used to delete existing resources |
Ideally, the resource should always be PLURAL, and as an API consumer, if someone is keen in accessing just one instance of a resource, you can try like this in the URL –
And in cases where a resource is under a resource, so say Students under School then few of the examples of API endpoint would be
Providing Meaningful feedback to Developer
When an API consumer sends a request to the server via an API, the client should receive an acknowledgment whether it succeeded, failed or incorrect request was received. A bunch of standardized HTTP codes is available that helps in debugging a particular scenario. Make sure server is coded appropriately to return the right status code.
| Status Code | Explanation |
| 200 [Ok] | The standard HTTP response narrating success for GET, PUT or POST |
| 201 [Created] | Used whenever a new instance is created.
E.g., on creating a new instance, using POST method, should always return 201 status code. |
| 204 [No Content] | It narrates about a request that is successfully processed but has not returned any content.
Eg: DELETE /school/54/students/2 This would delete student 2 of school 54 but as it does not have any data to return it would not return anything. |
| 304 [Not Modified] | When the processed query result is already present in the API consumers cache, it does not need to be reprocessed. |
| 400 [Bad Request] | When the call made to the server is not a valid query. |
| 401 [Unauthorized] | When the credentials do not match.
Example – When a teacher record is being accessed by a student credentials |
| 403 [Forbidden] | It narrates that the query sent is valid, and the client is a valid user, but the client has restricted access to the page/resource for any reason.
E.g.,if you are trying to edit a record but the credentials you are using is just having read permissions. |
| 404 [Not Found] | It indicates when the requested data is no longer existing. |
| 410 [Gone] | It indicates the requested data has been moved and not to be found at this path. |
| 500 [Internal Server Error] | It narrates that the query is valid, but the server is confused,and the server is asked for some additional information or to meet some unexpected condition. |
| 503 [Service Unavailable] | It narrates that the server is unavailable/down to receive and process the request.
Example – when a website is under scheduled maintenance. |
Focus on Authorization and Authentication
Each API call made to the server precedes with valid authorization and authentication of the API consumer. Securing the code and data is of utmost importance while designing an API. Just for example when a banking app is interacting with the HR payroll, they would need READ permissions and not necessarily EDIT/AMEND permissions. So such type of validations need to dictate while the user is redirecting to the third party app.
Handling Complexity – searching, sorting and filtering
Each API call returns a set of data to the API consumer, how the client searches data is not in your hands, but the way you can produce results is in yours. Hence handling complex search queries with filters and sorts need to be handled carefully. You may not want to come across a situation like a server overload, or a performance issue. So in cases where there is a lot of data, you may need to limit the number of rows being displayed to improve performance.
For example – As an API developer, you could sweep properties and limit responses behind the ‘?’ in a query parameter, or isolate the specific component of the data the client is working with using a path parameter.
Picking the same example of schools and students, as a user wants all the students of location Boston with age 13
GET /students?location=boston&age=13&limit=10
Versioning for smoother Upgrades
With a dire need to push latest features frequently into the production environment, it’s a nightmare to assure that existing workflow is working as it is. Hence versioning each of the release made would help in debugging the buggy software release and helps in providing a stable interface to your clients.
Example – “http://api.yourservice.com/v1/schools/34/students”
TEKNOSPIRE – Presenting Well Designed API’s
Teknospire with an API driven model has been listed with Oracle marketplace and is available for the use of Payments. Teknospire has recently collaborated with Latin American APIs aggregator “Finconnecta” that is a FinForwardAccelerator to help inclusion and digitization. For more information on our products and services, please explore our website or contact us here.
While Open API, Open banking,and API usage are on the rise, empowering businesses to come up with innovative and dynamic applications. As developers, we need to assure the security aspects of an API. As if developer neglects and hackers find vulnerabilities in your API design, it could open gateways for malicious activity.