We all started with Web Development with some MVC framework initially(at least I did). Web apps back then would start a thread with new requests, the thread would process the request, and a “view” (HTML) would be generated and given to the client to render.
Layer after layer of inadequate software architecture, system design, size, and technical rot would crumple systems. In addition, tremendous amounts of valuable intellectual property — business rules, procedures, and workflows — were tightly coupled and a lacked reusability.
The progress
Since then, we've made significant progress. We could use reusable libraries to create better monolithic applications, but what if we wanted to create scalable(horizontal and vertical) architectures that could be distributed over several computing resources? What if we wanted to support desktop, online, and mobile devices with as much reusability and central control as possible?
Eventually came the world of APIs. The concepts of distributed software APIs and how simple Request/Response protocols may power almost any business activity were popularized by SOAP and REST.
With this evolution, we often found every team having 3 main pillars - the data person(dealing with data store), the service person(Writing APIs and building scalable systems) and an UI person(creating the User Interfaces).
What makes an API beautiful ?
In today's world of SAAS, APIs are really a product that powers your UI and is as important as that shinier User Interface and underlying data pool/lake/ocean. Creating beautiful API is an art and these key factors determine how beautiful you APIs are -
- Consistency : refers to the idea that one portion of your API should appear to be identical to every other section of your API. Having a shared set of rules and patterns makes the API consistent.
- Simplicity : is the idea that the API and its models makes sense. Is the intent of your domain reflected in your models and paths(Domain Driven Design)? Do they organize information in ways that are simple to comprehend and process? Answering these questions makes the API simple for consumers to consume.
- Technically compliant : confirms that it follows the API Design best practices and is properly documented.
Check this blog on some of the best practices.
Tirthankar Kundu
Once our beautiful API is thought through, we can now go to the API first development approach.
API First Development
It states that the first part of API Development is the design of APIs. Ask yourself how you, as a consumer, would want to work with data and conduct actions to solve your business challenges, rather than how your entity diagrams and database would work. Then, to the best of your technical ability, develop an API to solve the challenge(s).
Once API is designed, the database person can now create stored procedures or queries to fetch the data from data source. Service person can create highly scalable APIs with queues and messaging systems and other powerful tools(you have many nowadays, thanks to cloud computing 😉). The UI folks can use the mocked APIs to create mockup, designs and interfaces.
With less overall interaction and dependency, teams can begin to stagger the completion of their swim lanes. Iterative feedback can be gathered, allowing the overall software development process to progress more quickly. API-first aims to achieve this.
This all looks good but what are the tools available to make this work?
Enters OpenAPI and RAML
OpenAPI provides a variety of capabilities to guarantee that APIs are thoroughly documented. Versions and query tokens and parameters, security specifications (JWT/oAuth/basic/etc. ), HTTP headers, multi-part request bodies, a bewildering array of response types, and some amazing modelling tools that reflect the needs of both static and dynamic type systems present in today's back-end services can all be specified in paths. It was formerly known as Swagger.
RAML (RESTful API Modeling Language) is a YAML-based modelling language that is used to represent RESTful APIs. It gives a well-structured and easy-to-understand framework for describing the API. It "makes it straightforward to manage the entire API lifecycle," according to RAML's website.
Hope you liked it. Cheers 🍻
