- Uniform Resource Locator (URL) indicates that it talks about a resource and its location so ideally every URL should tell about a resource or its collection, API is no exception.
- API endpoint must be a name of resource, being more specific, it must be a noun in English
/api/v1/departments/5/employees/api/v1/departments/5/get-employees - API endpoint must not indicate actions. In other words it should not contain English verbs
/api/v1/departments/5/employees/api/v1/departments/5/get-employees - Ideally one endpoint must provide information about one resource type only (micro-services!).
/api/v1/departments/5/employees/api/v1/departments-and-employees - Avoid using underscores and use hyphens (only if needed) to avoid readability issues. Sometimes if you use hyphen or underscore to join / combine two resources then strictly avoid it.
/api/v1/employee-types/api/v1/employee_types - Do not keep struggling with lower and upper cases. Keep it simple - everything in small case
/api/v1/departments/5/employees/api/v1/Departments/5/Employees - Pluralise endpoint when you return collection of resources/records
/api/v1/departments/api/v1/department - Singularise endpoint when you return single resource/records
/api/v1/departments/5/employees/1001/basic-info/api/v1/departments/5/employees/1001/basic-infos - PUSH method is used for creating/adding a resource in its parent collection so avoid using singular endpoint.
PUSH /api/v1/departments/5/employeesPUSH /api/v1/departments/5/employee - PUT, PATCH, DELETE methods are generally used to update or delete single resource so avoid using plural endpoint (unless and until you want to bulk edit or delete resources)
- Its always good to add version in your api routes so that you can keep same name for future versions keeping current version intact (No modifications to api once deployed). Also, it helps you to deprecate older ones.
All guidelines mentioned above are guidelines to write correct APIs. You can still overrule them for a really good reason.
No comments:
Post a Comment