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.




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.







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!

Thank you for taking out time to read the above post. Hope you found it useful. In case of any questions, feel free to comment below. Also, if you are keen on knowing about a specific topic, happy to explore your recommendations as well.
For any latest updates or posts on our website, you can follow us on LinkedIn. Look forward to connecting with you there.

Share this:
Notify of
Inline Feedbacks
View all comments