API Design First with webhook APIs

API Design First is regarded as best practice and now with the ASYNC API specification, it’s possible to achieve API Design First with webhook APIs. In this blog post, I’ll take you through what is API Design First and why it’s best practice. I’ll also introduce you to the ASYNC API specification and how it can be used to describe your webhook APIs and finally I’ll wrap it up with an example of how you can use the ASYNC API specification together with webhook API management software, such as webhookie, to achieve rapid backend integration that also has the added benefit of high quality, reusable APIs.

API Design First

Build first vs design first.. that is the question.. at least when it comes to developing APIs. The answer should be obvious, however, as one of the side-effects of the agile movement, it became a bit blurred. To be clear, it’s not agile that is to blame, it is the common misconceptions of what agile software development is, that is to blame. Let’s also be clear that build first is not all bad either, APIs are very useful assets so having them is great. It’s just that design first usually gets a better outcome, promoting improved (re)usability, extensibility, and maintainability.

API design first means what it says, that you design the API before you start building it. When designing an API you use a specification, such as the openAPI specification (OAS) or the ASYNC API specification, that can then be used to implement the stub code in the client and server as well as make the API discoverable in a portal. Those are not the only benefits of using a standard specification like OAS or ASYNC API. A big benefit of design first is the ability to decouple two separate concerns of development. In the case of REST APIs, it is often the case of decoupling the backend development from the frontend development. In the case of ASYNC API, it is the case of decoupling one backend system/service development from another backend system/service development. This means that both concerns can work in parallel which leads to faster development and deployment time.

Design first also has a host of other tangible and non-tangible benefits. With the design done in a matter of minutes or hours, it’s easier for stakeholders to challenge and improve the design. Whether it’s the semantics of the API or the structure, there is the possibility to easily adapt it as there is less investment in the interface than there would be if there was code behind it. This leads to APIs and portfolios of APIs that are more consistent and coherent – which leads to higher adoption and an improved developer experience – which in turn results in a better developer culture and that has a host of benefits.

ASYNC API Specification

The widely popular Open API Specification has enabled many tools to be built that have helped companies adopt and implement APIs.  Well, more accurately, it has helped them adopt and implement REST-style APIs. While that statement is not 100% correct, many of you will tend to agree that this is where OAS fits best. Identifying and acknowledging this limitation of OAS, the ASYNC API specification was born to provide, what REST APIs have had now for a long time, – a solid foundation for the asynchronous event-based APIs. 

With the ASYNC API specification, we now have verbs like subscribe and publish with channels (i.e topics), along with the security and schema modeling that exists in OAS. In fact, as we see it, the ASYNC API specification has given birth to the webhook API. An API that describes your product’s webhook capability, similar to how a REST API describes your product’s rest capabilities. 

Hello World Example

Let’s take an example to see the steps involved to get started with API design first, webhook APIs, and the ASYNC API Specification:

  1. Find your favourite ASYNC API editor – two examples here are the ASYNC API playground – AsyncAPI 2.0.0 playground or you can use your webhook API management software such as webhookie.
  2. Create the topics/channels that you want to be available in your API. In this example, we’ve gone for one topic in our API called helloWorld
  3. Specify the security options that are available for the callbacks to use. In this example, we have only the HMAC signature as an option
  4. Specify the payload of the topic
Hello World webhook API

Now that you have a draft specification of your webhook API you can use it to generate code on the consumer side. It can also be used to load into your webhook API management software so that you can make the API discoverable and give your consumers the ability to subscribe to it.

For these next steps, we will use webhookie Community Edition (Open Source webhook API management software)

  1. In webhookie create a new webhook API.
  2. If you’ve created the specification outside of webhookie you can paste it into the webhook API editor.
  3. Choose which consumer groups should be able to discover and subscribe to the API and which provider groups can manage the API.
  4. Publish the API
webhook API gallery

Now with Specification created and published in webhookie your downstream consumers and API stakeholders can review the API and once ok with the contract both the provider and consumer can start their development process. This would involve the steps of:

Consumer side:

  1. Downloading the ASYNC API specification
  2. Using an ASYNC API code generating tool (check out Tooling | AsyncAPI Initiative for event-driven APIs )  to generate the consuming stub code.
  3. Implement your code to integrate the data into your backend system.
  4. Use the Test functionality in webhookie to test your callback against the webhook API.
  5. Once testing is complete and you are ready to start the end-to-end testing you can subscribe to the webhook in webhookie. Now as a consumer you are ready to start receiving events into your system.

 Provider side:

  1. Implement the code to generate your events
  2. Publish them to your webhook API infrastructure (again using webhookie) using either the REST API or AMQP and you’re done.

 There you have an end-to-end example of using an API design-first approach that integrates two systems, using a webhook API, with real-time data.  Backend integration generally takes months to implement and deploy. With this approach, you can significantly cut down on the time taken to integrate and increase the quality of it at the same time. You also have as a bi-product a reusable API interface so that any other downstream system can just as easily subscribe and get going.

I hope you got something from reading this blog post. Please leave a comment if you appreciated it and good luck with your API implementations!

  1. This is pretty good feature! Would be much appreciated if get any bock to explain the difference between Couldevents Spec Vs AsyncAPI. Thanks!

2 comments

Leave a comment

Your email address will not be published.