Choosing a great API spec saves time and hassle
An important part of API development best practices is planning the API spec. An API spec consists of a plan of how your API should look structurally - like a blueprint of a house. It’s a key part of API development because it can help you isolate design flaws or problems before you write a line of code.
In a process called Spec-Driven Development, you’ll be able to create a long-lived API; developing your API while keeping the API spec in mind can help you catch any glitches or inconsistencies early on. This process can add two to four weeks onto the development cycle, but it’s a worthwhile investment. Planning the API spec up front can save you months and perhaps years of hassle as you struggle with poor design or even having to build a new API from scratch.
The idea behind a REST API is simple: it should be flexible enough to endure. That means as you build your API, you want to plan ahead—not just for this development cycle, not just for the project roadmap, but for what may exist a year or two down the road. This is really where REST excels, because with REST you can take and return multiple content types (meaning that if something comes along and replaces JSON, you can adapt) and even be fluid in how it directs the client with hypermedia. Right off the bat you are being set up for success by choosing the flexibility of REST. However it’s still important that you go in with the right mindset—that the API you build will be long-term focused.
Spec-Driven Development encourages separating the design stage from the development stage and approaching it iteratively. This means that as you build out your design using a standardized spec (such as RESTful API Modeling Language aka RAML), you can test that spec by mocking it up and getting user feedback.
In the book Undisturbed REST: A guide to designing the perfect API, an in-depth guide to successful API Spec-Driven Development is presented, along with comparisons of the various API specs. Download a copy to learn more about this crucial stage of API design.
Next, find out more on keeping your APIs secure.