Mulesoft has an excellent article on API design based on Specifications. Some best practices in API design include:
-Don’t design the API your code, instead code the API to its definition
One of the main benefits of Cloud computing and proper architecture design is to utilise pattern design and code reuse to ensure that the API remains the same across the full interface, keeping resources and methods alike standardized and easily implemented (or reused).
Tools like API Designer allow you to view your API as it is being designed and watch for inconsistencies/ dependencies you might have missed otherwise. Once the spec is in place it ensures that the API works consistently. To build a proper API design you need to use RAML (Rest API modelling language), which offers a simple, semantic, and human readable format to describe the API. Mule’s API Designer makes this process straightforward and shows what the API will look like as you describe it.
(Figure is from mulesoft.com)
Mock Your API and get User Feedback
Example: We can use the API Notebook to handle complex security or login negotiations like OAuth while providing tool tips to walk users through the different API resources and methods, letting them try out and explore your API without server-side coding or having to dig through extensive documentation.
(Figure above is from Mulesoft.com)
This process can be repeated as necessary in order to develop the right API for clients. By following the above steps and carefully building the API design, it will conform to the specifications and be de-coupled from users and back-end resources, ensuring a longer life, than if you designed the API from the code.