Whether it is top down or bottom up approach, it is generally advisable to start on the mock servcies, api test plans, documentation along with the design. With modeling languages like RAML, Swagger and tools around these languages, you can have a live API experience while implementation is in progress, generate client / server code, create test cases and help in production monitoring.
Both Swagger and RAML provides api definition language, however it seems that they are distinguished by the vendor support and the tooling that support these specs. In its current state, both supports basic design elements of the RESTful like URIs, methods etc, however they may approach advance elements differently like Hypermedia, complex methods etc.
Companies like Apigee, Reverb supports Swagger
- Swagger was released in 2011. has the most active developer community, extensive number of tools in most languages.
- Swagger creates a new section for each endpoint/verb which provides less level of nested indentation, which provides better readability but makes the API view granular at method level than at resource level.
- Node has a swagger module which creates a swagger.yml in the api folder of a node.js app. Project edit opens a swagger UI which dynamically changes the API view based on the changes in the swagger.yml file.
- Swagger CodeGen is a template driven engine to generate client code in different languages.
- Swagger version is 2.0 and has been given to Open API initiative and has been renamed as Open API Specification supported my members like Apogee, Google, Microsoft, SmartBear etc
Companies like MuleSoft, SOA supports RAML
- RAML is somewhat newer releases in 2013, has an active developer community and supports tools in most languages if not all.
- RAML is grouped around endpoints with drill down into verbs and keeps the needed visibility around resource level rather than verb level, however it does make it less readable with extensive nested indentation.
- As an offering in Anypoint Platform, MuleSoft has an API Designer to create RAML specs. It also has an APIKit which generates Mule flows for the each URIs in a Mule Application.
- API Notebook is another tool by MuleSoft that is used to create client code to test use cases by composing different API calls and is based on Javascript.
- RAML version is 1.0 and supported by vendors like amazon web services, ca technologies, mulesoft.
No comments:
Post a Comment