BEST PRACTICES TO OPEN API DESIGN
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] Societies Residents 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 – method GET path /companies should get the list of all companies method GET path /companies/43 should get the detail of company 43 method DELETE path /companies/43 should delete company 43 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 GET /schools/5/students should get the list of all students from school 5 GET /schools/8/students/45 should get the details of student 45, which belongs to school 8 DELETE /schools/9/students/54 should delete students 54, which belongs to school 9 POST /schools should create a new school and return the details of the new school created 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
