Distributed team with multiple people working on different part of the project. Co-ordinating and being on the same page is difficult. But if there is an aggrement about the API beforehand, integration can go in parallel and does not have to come at last. Agreement also helps UI (Design team) to work independent with the API team and does not have to worry about the server being constantly restarted and redeployed. We will use RAML to design the API and use pre-existing RAML tool to generate the html pages that makes it easy to understand the APIs and RAML mock services. Mock services helps to test the API during the initial phase of development.
RAML - RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices.
I have designed a small API to show the benefits and advantage of RAML. The API is a toy example.
npm install -g raml2html
Once raml2html is installed you can generate the HTML as shown below:
raml2html music.raml > music.html
This produces the HTML file that is easy to understand. I have attached some screen-shots here.
npm install -g osprey-mock-service
Start the osprey-mock-service from the CLI. This will automatically use the baseUri as the path to the mock service. For example, http://example.com/api will result in http://localhost:{PORT}/api.
osprey-mock-service -f music.raml -p 8000
The parameters in the above command are
- -f Path to the root RAML definition (E.g. /path/to/api.raml)
- -p Port number to bind the server locally
Once you have stated the mock service you can make the request from the browser or other HTTP clients.