In many ways, building an API is like building a house. You need blueprints or else chances are it isn’t going to turn out exactly the way you had hoped.

At NEWTOMS, we first ask ourselves, “who is the API for?”. As developers, we tend to like to skip this question. Are you building the API for the business’ direct customers? For business partners? Or for third-party developers so that your platform can be extended upon? Often the answer tends to be a combination of the above, but until you understand for whom you are building your API, you aren’t ready to start planning it.

When we build an API for a client, we sit down with the business NEWTOMS is a strong advocate of the Spec-Driven approach when we work with our clients as it ensures that their APIs are well thought out, widely used and reused in the long-term. owners to understand what is it they want us to build. Once we have answered that question, we involve the actual users in the process by asking:

What actions would you like to be able to accomplish through an API?

By speaking to the potential users, we find out exactly what they’re looking for and isolate our company’s value to them. Once we have this information we can build out the API while testing it for real use cases and in doing so, we alleviate an existing pain.

Once we understand why we are building the API, and what it needs to be able to accomplish, we can start creating the blueprint or API spec. Going back to the building a house scenario, by having a blueprint of how the API should look before writing a line of code can prevent many design flaws and problems down the road.

At NEWTOMS, we favor a process called Spec-driven development. We believe in this approach because it allows us to build APIs for the long term while also catching early on:

  • Glitches
  • Inconsistencies
  • Design issues

This process typically adds 2-4 weeks onto the development life cycle, but it can save you months or even years of struggle caused by poor design, or even worse—find our client having to build a brand-new API from scratch.

Spec-Driven Development is designed to make the development, management, and documentation of our API even more efficient. This approach divides the design and development into two separate processes and approaches them iteratively.

What this means is that we design the API using a standardized spec such as RESTful API Modeling Language (RAML) and we test that spec by simulating it with the user and getting constant feedback.  Based on that feedback, we determine whether the spec is ready for development or return to the design stage where the cycle continues.

Once we polish the design in the spec, we can use that specification as our design blueprint.

In essence, we are implementing agile user testing, and agile development which is key in Spec-Driven development.

It’s important to understand that there is no back and forth in Spec-Driven development. Should we encounter an issue, rather than correcting it in the development phase, we stop and go back to the design of the spec to fix it and retest it. The reason behind this is to encourage an “all-hands-on-deck” mindset instead of making changes on the fly and fixing things with a short-sighted view

To execute the Spec-Driven approach successfully, we need to keep the following constraints in mind:

  • Standardized

    • The following specs are considered standard or common in the industry: RAML, Swagger, API Blueprint, IO Docs. The Spec-Driven approach calls for a standardized approach across the board because it facilitates easy portability among developers. At the same time, a standardized approach allows the spec to be consistent in its own format
  • Consistent

    • it’s important that we use pattern-driven design and reuse code whenever possible so that each aspect of our spec is consistent. The whole point is to avoid confusion so all aspects of the application work similarly and the end user has the freedom to move seamlessly.
  • Tested

    • The Spec-Driven approach requires a strong Tested spec to build a reliable API. We believe the spec must be carefully crafted and tested with both internal and external uses to be sure that it can meet the needs of all parties
  • Concrete

    • The spec should be Concrete as it is the foundation of the house we are building. It should encompass all aspects of the application so that it can be a solid blueprint to which our developers can code
  • Immutable

    • which in this context means the code should not deviate from or override the spec as this can affect the API’s longevity.
  • Persistent

    • This is probably the most important constraint to stick to when following a Spec-Driven approach. For every change you make to the API, we need to go back to the design stage, testing the changes, and then once validated, start adding the code and pushing the changes to production.

NEWTOMS is a strong advocate of the Spec-Driven approach when we work with our clients as it ensures that their APIs are well thought out, widely used and reused in the long-term.

We are more than happy to discuss the advantages of this approach with your organization. Feel free to contact us at We respond to any request 24/7 because our staff is strategically located around the globe. We speak English, Spanish, and Filipino.

You can find us on Facebook, Twitter, LinkedIn and Instagram

Uncover the possibilities and create opportunities for your business by having these solutions powered by MuleSoft and implemented by NEWTOMS.

Winston J. Rivero Jr.

Winston J. Rivero Jr.

Winston J Rivero Jr. graduated in two careers: Finance & Marketing from Georgia State University in 2012 – He's currently the Director of Business Development in North America and leads the Content Marketing Strategy for NEWTOMS