Expanding on my previous posts about
- annotating and validating JSON data structure with JSON Schema
- defining and documenting REST APIs using Swagger
I have two additional suggestions for tools that help you define and build HTTP-based APIs in a less haphazard, more deliberate manner:
- JSON API: While JSON Schema allows you to annotate and validate JSON-based data types JSON API gives you clear, opinionated guidelines for structuring JSON API responses so you don’t have think about those implementation details yourself. Having uniform guidelines for API responses also helps with simplifying inter-app communication: If several applications use the same basic format for their API responses, mutually consuming those responses becomes a whole lot easier.
- Open API Initiative: Based on Swagger SmartBear have started the Open API Initiative (OAI), which now includes big players like Google, Microsoft, PayPal and IBM. The purpose of this initiative is to provide a standardised way for describing REST APIs in a vendor-independent manner.