Today I was pulled in the processes again. Previously I introduced the Documentation-First approach. That actually takes advantage of design-first approach is well better known than documentation-first. I could say that those are siblings if not identical twins. With the identical twins only the trained eye can see the difference.
In design-first approach you use wanted API specs format and define the needed endpoints, data models, parameters and methods. You don’t implement the API. Instead you use mocking services to see how the design would behave and what is the feeling of that API. After you have designed and lightly tested the API you can pass the design forward for implementation. Currently the API Design tools are API spec format driven although more business or human driven approach would likely work better. But developing such tool is not simple task. Now we have to manage with the spec / technical approach driven tools.
When Developer Experience Matters
Design-first is selected when the Developer eXperience matters most. According to Keshav Vasudevan in SwaggerBlog
- “A well designed API can do wonders for the adoption and consumption of your APIs, and good design can be better achieved with the Design First approach.”
- “The biggest reason to go for the Design First approach is when your API’s target audience are external customers or partners.”
- “Spotting issues in the design, before writing any code is a much more efficient and streamlined approach, than doing so after the implementation is already in place.”
I agree with the above and I would add fourth item in the list. With Design-First approach you are more likely to insulate API developers (implementers) from customer noise. That contains an assumption that you have a clear method to collect customer needs and those are processed by dedicated API Designer (role). Assuring peace and quiet irritation free time for the actual implementers of the API was one of the primary reasons to apply design-first in Platform of Trust API development.
The above is part of the API Development Process in our platform. It all starts from customers telling us their pains. Designer picks the issues and starts to deal with the pain. Designer makes a decision is the solution for the pain breaking or non-breaking change. Based on that design task is pushed to either in current API version development or to the next version.
In addition to that design-first reduces the risk of failure by ensuring that APIs are reliable, consistent, and easy for developers to use. Keep in mind that designer is using API Design Guide which makes the design process faster and results have higher quality. Benefit is also that we don’t use resources to something that is not requested by the clients (can be achieved with code-first too). We use SwaggerHub in design management. That environment gives the designer mocking service as well. Of course mocking is always mocking and final verification must be done in different environment. Nevertheless mocking helps in getting the design “right”.
Work in parallel with QA
With design-first our QA can work with the designer in parallel. They can craft the tests before the implementation begings. It’s also tempting to generate tests from the API spec files. API testing is a type of software testing that aims to validate the expectations of an API in terms of functionality, reliability, performance, and security. Specification-based API testing is the verification of the API using the available functionalities defined in a specification document. In specification-based REST API testing, test cases consist of sending requests over HTTP/S and validating that the server responses conform to the specification, such as the OpenAPI one. For instance, a test case could be created for the operation findPetsByStatus of the famous Petstore example by sending a GET request to http://petstore.swagger.io/v2/pet/findByStatus?status=available and expecting a response having the HTTP status code 200 and a JSON array conforming the schema defined in the specification. Automated specification-based API testing involves generating such test cases.
Less vague specifications
No more vague specifications in Word documents or wikis. As a result of this process developers who actually implement the API changes will be given:
- ready design in machine-readable format
- tests to use in development (when test succeed task is done)
- in our case they can look at the final documentation going to the customer
- ready-made test code examples to fiddle with (eg try the API really)
Changes are inevidable
Of course the design might be sligthly changed in implementation. That is something you must accept. Designer most likely does not know all the possible obstacles ahead. Neither does the developer. In most cases developer can see how a feature can be implemented but surprises are certain. Remember Ten Commandments of Egoless Programming and especially this one “The only constant in the world is change. Be open to it and accept it with a smile. Look at each change to your requirements, platform, or tool as a new challenge, not as some serious inconvenience to be fought.”
We started the development code-first because that provided speed. Now it’s time we make a transition to more sustainable mode of Development model.
Some more to read from 100 Days DX
- #100 - The biggest open resource on Developer eXperience so far
- #99 - Hackers - the top 1% of engineers
- #98 - Invalid Open API spec files ruins the developer experience
- #97 - Lightweight API evaluation framework
- #96 - Embracing open source community driven tools development
- #95 - Exploring the multilevel nature of API Design Guides
While you are here...
Check out Platform of Trust in which I've worked to enable best possible developer experience!