1) Terminologies<\/strong><\/span><\/h3>\nThe following are the most important terms related to REST APIs<\/p>\n
\n- Resource<\/strong> is an object or representation of something, which has some associated data with it and there can be set of methods to operate on it. E.g. Animals, schools and employees are resources and delete, add, update <\/em>are the operations to be performed on these resources.<\/li>\n
- Collections<\/strong> are set of resources, e.g Companies<\/em> is the collection of Company<\/em> resource.<\/li>\n
- URL<\/strong> (Uniform Resource<\/strong> Locator) is a path through which a resource <\/strong>can be located and some actions can be performed on it.<\/li>\n<\/ul>\n
2) API\u00a0endpoint<\/span><\/h3>\nLet\u2019s write few APIs for Companies<\/strong> which has some Employees,<\/strong> to understand more.
\n\/getAllEmployees<\/code> is an API which will respond with the list of employees. Few more APIs around a Company<\/strong> will look like as follows:<\/p>\n\n\/addNewEmployee<\/em><\/code><\/li>\n\/updateEmployee<\/em><\/code><\/li>\n\/deleteEmployee<\/em><\/code><\/li>\n\/deleteAllEmployees<\/em><\/code><\/li>\n\/promoteEmployee<\/em><\/code><\/li>\n\/promoteAllEmployees<\/em><\/code><\/li>\n<\/ul>\nAnd there will be tons of other API endpoints like these for different operations. All of those will contain many redundant actions. Hence, all these API endpoints would be burdensome to maintain, when API count increases.<\/p>\n
What is wrong?
\n<\/strong>The URL should only contain resources(nouns) not actions or verbs. The API path\/addNewEmployee<\/code> contains the action addNew<\/code> along with the resource name Employee<\/code>.<\/p>\nThen what is the correct way?
\n<\/strong>\/companies<\/code> endpoint is a good example, which contains no action. But the question is how do we tell the server about the actions to be performed on companies<\/code> resource viz. whether to add, delete or update?<\/p>\nThis is where the HTTP methods<\/a> (GET, POST, DELETE, PUT), also called as verbs, play the role.<\/p>\nThe resource should always be plural<\/strong> in the API endpoint and if we want to access one instance of the resource, we can always pass the id\u00a0in\u00a0the URL.<\/p>\n\n- method
GET<\/code> path \/companies<\/code> should get the list of all companies<\/li>\n- method
GET<\/code> path \/companies\/34<\/code> should get the detail of company 34<\/li>\n- method
DELETE<\/code> path \/companies\/34<\/code> should delete company 34<\/li>\n<\/ul>\nIn few other use cases, if we have resources under a resource, e.g Employees of a Company, then few of the sample API endpoints would be:<\/p>\n
\nGET \/companies\/3\/employees<\/code> should get the list of all employees from company 3<\/li>\nGET \/companies\/3\/employees\/45<\/code> should get the details of employee 45, which belongs to company 3<\/li>\nDELETE \/companies\/3\/employees\/45<\/code> should delete employee 45, which belongs to company 3<\/li>\nPOST \/companies<\/code> should create a new company and return the details of the new company created<\/li>\n<\/ul>\nIsn\u2019t the APIs are now more precise and consistent? \ud83d\ude0e<\/p>\n
Conclusion: <\/em><\/strong>The paths should contain the plural form of resources and the HTTP method should define the kind of action to be performed on the resource.<\/em><\/p>\n3) HTTP methods\u00a0(verbs)<\/span><\/h3>\nHTTP has defined few sets of methods which indicates the type of action to be performed on the resources.<\/p>\n
The URL is a sentence, where resources are nouns and HTTP methods are\u00a0verbs.<\/span><\/em><\/strong><\/p><\/blockquote>\nThe important HTTP methods are as follows:<\/p>\n
\nGET<\/code> method requests data from the resource and should not produce any side effect.
\nE.g \/companies\/3\/employees<\/code> returns list of all employees from company 3.<\/li>\nPOST<\/code> method requests the server to create<\/strong> a resource in the database, mostly when a web form is submitted.
\nE.g \/companies\/3\/employees<\/code> creates a new Employee of company 3.
\nPOST<\/code> is non-idempotent<\/a> which means multiple requests will have different effects.<\/li>\nPUT<\/code> method requests the server to update<\/strong> resource or create<\/strong> the resource, if it doesn\u2019t exist.
\nE.g. \/companies\/3\/employees\/john<\/code> will request the server to update, or create if doesn\u2019t exist, the john<\/em> resource in employees collection under company 3.
\nPUT<\/code> is idempotent<\/a> which means multiple requests will have the same effects.<\/li>\nDELETE<\/code> method requests that the resources, or its instance, should be removed from the database.
\nE.g \/companies\/3\/employees\/john\/<\/code> will request the server to delete john <\/em>resource from the employees collection under the company 3.<\/li>\n<\/ol>\n
2) API\u00a0endpoint<\/span><\/h3>\nLet\u2019s write few APIs for Companies<\/strong> which has some Employees,<\/strong> to understand more.
\n\/getAllEmployees<\/code> is an API which will respond with the list of employees. Few more APIs around a Company<\/strong> will look like as follows:<\/p>\n\n\/addNewEmployee<\/em><\/code><\/li>\n\/updateEmployee<\/em><\/code><\/li>\n\/deleteEmployee<\/em><\/code><\/li>\n\/deleteAllEmployees<\/em><\/code><\/li>\n\/promoteEmployee<\/em><\/code><\/li>\n\/promoteAllEmployees<\/em><\/code><\/li>\n<\/ul>\nAnd there will be tons of other API endpoints like these for different operations. All of those will contain many redundant actions. Hence, all these API endpoints would be burdensome to maintain, when API count increases.<\/p>\n
What is wrong?
\n<\/strong>The URL should only contain resources(nouns) not actions or verbs. The API path\/addNewEmployee<\/code> contains the action addNew<\/code> along with the resource name Employee<\/code>.<\/p>\nThen what is the correct way?
\n<\/strong>\/companies<\/code> endpoint is a good example, which contains no action. But the question is how do we tell the server about the actions to be performed on companies<\/code> resource viz. whether to add, delete or update?<\/p>\nThis is where the HTTP methods<\/a> (GET, POST, DELETE, PUT), also called as verbs, play the role.<\/p>\nThe resource should always be plural<\/strong> in the API endpoint and if we want to access one instance of the resource, we can always pass the id\u00a0in\u00a0the URL.<\/p>\n\n- method
GET<\/code> path \/companies<\/code> should get the list of all companies<\/li>\n- method
GET<\/code> path \/companies\/34<\/code> should get the detail of company 34<\/li>\n- method
DELETE<\/code> path \/companies\/34<\/code> should delete company 34<\/li>\n<\/ul>\nIn few other use cases, if we have resources under a resource, e.g Employees of a Company, then few of the sample API endpoints would be:<\/p>\n
\nGET \/companies\/3\/employees<\/code> should get the list of all employees from company 3<\/li>\nGET \/companies\/3\/employees\/45<\/code> should get the details of employee 45, which belongs to company 3<\/li>\nDELETE \/companies\/3\/employees\/45<\/code> should delete employee 45, which belongs to company 3<\/li>\nPOST \/companies<\/code> should create a new company and return the details of the new company created<\/li>\n<\/ul>\nIsn\u2019t the APIs are now more precise and consistent? \ud83d\ude0e<\/p>\n
Conclusion: <\/em><\/strong>The paths should contain the plural form of resources and the HTTP method should define the kind of action to be performed on the resource.<\/em><\/p>\n3) HTTP methods\u00a0(verbs)<\/span><\/h3>\nHTTP has defined few sets of methods which indicates the type of action to be performed on the resources.<\/p>\n
The URL is a sentence, where resources are nouns and HTTP methods are\u00a0verbs.<\/span><\/em><\/strong><\/p><\/blockquote>\nThe important HTTP methods are as follows:<\/p>\n
\nGET<\/code> method requests data from the resource and should not produce any side effect.
\nE.g \/companies\/3\/employees<\/code> returns list of all employees from company 3.<\/li>\nPOST<\/code> method requests the server to create<\/strong> a resource in the database, mostly when a web form is submitted.
\nE.g \/companies\/3\/employees<\/code> creates a new Employee of company 3.
\nPOST<\/code> is non-idempotent<\/a> which means multiple requests will have different effects.<\/li>\nPUT<\/code> method requests the server to update<\/strong> resource or create<\/strong> the resource, if it doesn\u2019t exist.
\nE.g. \/companies\/3\/employees\/john<\/code> will request the server to update, or create if doesn\u2019t exist, the john<\/em> resource in employees collection under company 3.
\nPUT<\/code> is idempotent<\/a> which means multiple requests will have the same effects.<\/li>\nDELETE<\/code> method requests that the resources, or its instance, should be removed from the database.
\nE.g \/companies\/3\/employees\/john\/<\/code> will request the server to delete john <\/em>resource from the employees collection under the company 3.<\/li>\n<\/ol>\n
\n
\/getAllEmployees<\/code> is an API which will respond with the list of employees. Few more APIs around a Company<\/strong> will look like as follows:<\/p>\n\n\/addNewEmployee<\/em><\/code><\/li>\n\/updateEmployee<\/em><\/code><\/li>\n\/deleteEmployee<\/em><\/code><\/li>\n\/deleteAllEmployees<\/em><\/code><\/li>\n\/promoteEmployee<\/em><\/code><\/li>\n\/promoteAllEmployees<\/em><\/code><\/li>\n<\/ul>\nAnd there will be tons of other API endpoints like these for different operations. All of those will contain many redundant actions. Hence, all these API endpoints would be burdensome to maintain, when API count increases.<\/p>\n
What is wrong?
\n<\/strong>The URL should only contain resources(nouns) not actions or verbs. The API path\/addNewEmployee<\/code> contains the action addNew<\/code> along with the resource name Employee<\/code>.<\/p>\nThen what is the correct way?
\n<\/strong>\/companies<\/code> endpoint is a good example, which contains no action. But the question is how do we tell the server about the actions to be performed on companies<\/code> resource viz. whether to add, delete or update?<\/p>\nThis is where the HTTP methods<\/a> (GET, POST, DELETE, PUT), also called as verbs, play the role.<\/p>\nThe resource should always be plural<\/strong> in the API endpoint and if we want to access one instance of the resource, we can always pass the id\u00a0in\u00a0the URL.<\/p>\n\n- method
GET<\/code> path \/companies<\/code> should get the list of all companies<\/li>\n- method
GET<\/code> path \/companies\/34<\/code> should get the detail of company 34<\/li>\n- method
DELETE<\/code> path \/companies\/34<\/code> should delete company 34<\/li>\n<\/ul>\nIn few other use cases, if we have resources under a resource, e.g Employees of a Company, then few of the sample API endpoints would be:<\/p>\n
\nGET \/companies\/3\/employees<\/code> should get the list of all employees from company 3<\/li>\nGET \/companies\/3\/employees\/45<\/code> should get the details of employee 45, which belongs to company 3<\/li>\nDELETE \/companies\/3\/employees\/45<\/code> should delete employee 45, which belongs to company 3<\/li>\nPOST \/companies<\/code> should create a new company and return the details of the new company created<\/li>\n<\/ul>\nIsn\u2019t the APIs are now more precise and consistent? \ud83d\ude0e<\/p>\n
Conclusion: <\/em><\/strong>The paths should contain the plural form of resources and the HTTP method should define the kind of action to be performed on the resource.<\/em><\/p>\n3) HTTP methods\u00a0(verbs)<\/span><\/h3>\nHTTP has defined few sets of methods which indicates the type of action to be performed on the resources.<\/p>\n
The URL is a sentence, where resources are nouns and HTTP methods are\u00a0verbs.<\/span><\/em><\/strong><\/p><\/blockquote>\nThe important HTTP methods are as follows:<\/p>\n
\nGET<\/code> method requests data from the resource and should not produce any side effect.
\nE.g \/companies\/3\/employees<\/code> returns list of all employees from company 3.<\/li>\nPOST<\/code> method requests the server to create<\/strong> a resource in the database, mostly when a web form is submitted.
\nE.g \/companies\/3\/employees<\/code> creates a new Employee of company 3.
\nPOST<\/code> is non-idempotent<\/a> which means multiple requests will have different effects.<\/li>\nPUT<\/code> method requests the server to update<\/strong> resource or create<\/strong> the resource, if it doesn\u2019t exist.
\nE.g. \/companies\/3\/employees\/john<\/code> will request the server to update, or create if doesn\u2019t exist, the john<\/em> resource in employees collection under company 3.
\nPUT<\/code> is idempotent<\/a> which means multiple requests will have the same effects.<\/li>\nDELETE<\/code> method requests that the resources, or its instance, should be removed from the database.
\nE.g \/companies\/3\/employees\/john\/<\/code> will request the server to delete john <\/em>resource from the employees collection under the company 3.<\/li>\n<\/ol>\n