API URLs Best Practices
API URL plays an important role in organizing and categorizing the APIs in your organization. A good approach in defining API URL helps organization to categorize and manage them well. API URLs should map to the business domains and process they are catering to.
Here are few points which should be taken care of while defining the API URLs.
Environment – API URL should be able to tell which environment this API belong to.
Organization – API URL should be able to tell which Organization this API belongs to.
API layer – API URL should be able to tell the layer (system, process, and experience) this API belongs to.
API Version– API URL should be able to tell the version of the API
Business Unit- API URL should be able to tell the business unit this API belongs to
Business Process– API URL should be able to tell the business process this API belongs to
Sub business process – API URL should be able to tell the sub business process this API belongs to
Considering all the above points we can have API URLs as below.
https://api{env}.{organization}.com/{api–layer}/{api-version}/{business-unit}/{business-process}/{sub-business-process}/{resource}
Here are the examples of the above parameters in the URL. You will need to define the mapping rules in the dedicate load balancer (DLB) since mulesoft worker API URL cannot be modified.
| Parameter | Possible values | Description |
| env | “dv”,”qa” | dv for Dev, qa for QA. No need to have this value for production. |
| organization | mulesy | The organization which owns this API. |
| api-layer | “e”,”p”,”s” | “s” for system, “p” for process and “e” for experience layer. However, this should not be exposed to external consumers of your API. This parameter should remain internal. you should have DLB mapping to route to internal API path. |
| api-version | v1, v2 | v1 fir first version, v2 for second version |
| business-unit | “nutrition”, “beverages”, “confectionery” | It could be the business unit of your organization. Consider a FMCG organization which are into “nutrition”, “beverages”, “confectionery”. These are few typical business units of that organization which runs independently to each other’s |
| business-process | finance, customer, order-management | The are under a business unit could be used to identify the business process. E.g finance, customer, Order management etc |
| sub-business-process | accounts, payroll, payments, taxes, general-ledgers | A business process can further be drilled down to sub business process which can help in narrowing down the API URLs further. E.g. finance business process can be drilled down to various sub business process e.g. accounts, payroll, payments, taxes, general-ledgers etc. |
Here are few examples which we could define considering the above understanding. “students” and “teachers” are resources here.
https://apidv.mulesy.com/v1/trainings/mulesoft/tutorials/students
https://apiqa.mulesy.com/v1/trainings/mulesoft/tutorials/students
https://api.mulesy.com/v1/trainings/mulesoft/tutorials/students
https://api.mulesy.com/v1/finance/payroll/teachers
Please do let us know if you want to enquire more about the API URLs. Also let us know if you have any other approach in defining the API URLs. Happy reading and sharing!