While building APIs, are you more of a design-first or a code-first type of person? The former approach is usually done when designing APIs for clients, while the latter one is usually used for internal APIs.
At Bump we like to focus on design-first APIs because we think an API - be it RESTful, Messaging, GraphQL, … - needs more love during its design phase. This is why we have improved our tools to go in that direction.
By focusing on the API contract first, we step into the shoes of API consumers. And it is a great way to make sure we build consumer-friendly APIs. Thus making the API clearer, easier to use, and improving its adoptability.
However, until today, we had one missing piece to offer a good design-first approach for our users. Read on for some good news if you are a “design-first” person or maybe a good argument to convince you to become one 😊
API contract development
For clarity we will focus on a tiny API from our demo train company which retrieves the current logged-in users account details. It’s made up of a single GET /account endpoint.
Now, imagine you want to change the API to add a list of tickets in the user details, and also want to add a new endpoint to be able to fetch a specific ticket. The changes are easily described in human words, but what does it represent from your API contract point of view? You will modify the JSON or YAML contract with your favorite tool, but now what? git diff will probably be a bit hard to read…
This is where our new bump diff command comes into play.
Make sure to upgrade your bump-cli package to at least v2.1.0 to test it.
Straight from your CLI, you are now able to describe the changes made in your contract:
> bump diff --doc users-account api-specification.yaml
Updated: GET /account
Response modified: 200
Body attribute added: ticket_ids
Added: GET /tickets/{ticket_id}
The new command will output a quick summary of what has changed between your latest deployed API contract and the one you have changed locally.
If you need more context, with a visual diff for instance, you can even use the --open flag to open the diff directly in your browser:
> bump diff --open --doc users-account api-specification.yaml
The command will return the diff summary and open this documentation diff in your browser
Collaborating on API design
So, you have made some changes to the contract locally but now you want to receive suggestions and reviews from your team. It’s a good time to open a pull request.
If you use Github Actions to launch your automation workflows, we have some more good news for you: we now offer a stable bump-sh/github-action@v1 action. And this release includes automatic API contract changelog pushed as a comment for each pull request.
Your team can now directly discuss on the pull request and suggest improvements by reading the diff summary without needing to dig into the JSON diff - which you’ll have to admit is a PITA to read 😅 -. If you update the contract again, the initial comment will be updated accordingly.
We find this bot comment really useful because it helps the team to jump in API design decisions quickly without having to step into a full code review. And it’s a win-win situation, because the person implementing the changes doesn’t have to focus on the code directly to receive quick feedback.
More to come soon
If you are still unsure whether you want to work with a design-first or code-first approach when building your APIs here are two good reads from the community:
- A design-first example from the AsyncAPI community
- a comparison of both methods from the OpenAPI community.
Regarding our two novelties, if you want to try them, you can visit our dedicated help pages or contact us anytime:
You will soon see some more improvements, on the way we display diff summaries, helping you identify breaking changes by warning the reviewers or even break the Continuous Integration checks if you desire… So stay tuned.
Until then we will continue to work on one of our initial mission: “Git diff, for your APIs”.
Have fun, stay free and stay kind.
✨
Oldest comments (0)