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:
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:
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 firstname.lastname@example.org. 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. 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