Design-first vs code-first approaches to APIs


Starting from the design of an API, then implementing later, has a lot of advantages. But most of the time people start with code and generate an API. In agile development, there are many cycles of this, whether you start with the design or with the code. At MuleSoft we have a lot of opinions about this, as do others in the RAML workgroup, and it’s not black and white – let’s hear and discuss your opinion here. And don’t pull any punches!


Starting with the spec allows architects and technical PMs to set an example when conceptualizing a new set of interfaces and then iterate with their API consumer customers. The very idea of iterative design demands that rapid experimentation is achieved via as little code as possible.

On the flip side, for established domains, the developers can implement faster if they just start coding. The truth is in either case it is a good practice to document the API contracts right from the start even if you plan on iterating. Ideally, there is round-trip generation from RAML to code annotation and vice versa that allows all stakeholders to use whatever they are most comfortable and not get in the way of the other.


This depends on the size of the API definition, right? I imagine that one could scribble some concepts down & start coding a simple API, whereas a meatier one with multiple endpoints may need a spec first. Documenting details in a spec would also be better for a team of developers … seems like it’s all on a case-by-case basis.


Dr Roy Fielding stated that people are really good at short - term design but usually awefull at long term design because we tend to design for the current release.

  • Generally as we are writing code or are designing it we tend to think about what we need now and not what we will need in a year or in five years. Using a design first approach we can “see” what our API looks like. RAML allows us also to test our design, to review it with design patterns, to check consistency and conformity of resources and methods, and to mock - test our endpoints, in such a way that a user would intereact with the API as though he was making real calls.

Therefore even before writing a single line of code you may be able to see if the future API will totally meet your needs or if there are inconsistencies somewhere, or if some of the features are completely incoherant or non - cohesive, etc.

When using a code - first approach we may not see some of the design flaws early enough. They may appear only after one or two versions are released into production. Then it is really costly to fix and would probably generate important risks of backward compatibility issues: that would be a thorn in the side of the API editor.

Now something that would be great about which I am thinking: the ability to use a bottom - up approach to annotate legacy code in order to generate .raml file from it and then check that file against somekind of raml schema that is used as the main design for the overall solution. This would allow us to “fix” legacy modules and integrated them in the main branch in conformity with the main raml-based API design.