An important part of the API development process 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.
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.