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
-Use RAML (REST API modelling language), so you can quickly build out your API in a consistent manner using code and pattern reuse.
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
RAML will allow us to ‘mockup’ the API and test it. Clients may also test this mockup. We can deploy the mock-up using MuleSoft’s API Designer as a service that gives us a URL that can be shared with other developers. This allows us to test the API design by making real calls as if they emanated from a real application. This process and the example responses defined in the RAML file will quickly identify problems and inconsistencies. As well, using Javascript and tools such as API Notebook, developers can interact with the Mock API without having to code the calls.
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.