Translating API Design into HTTP

How to create well-defined HTTP API specifications

The critical element in prototyping is to turn our original API design into a valid HTTP design. We need to convert the list of properties and actions from our ALPS description into a well-defined HTTP API specification. This is where the magic happens—the art of translation. We use the word art because there is no science or engineering that can properly convert our design into a protocol-specific definition. We still need to rely on creative people to do this work. That’s why sketching and prototyping can be so handy. It lets us work out decisions quickly and easily without a lot of expense.

It’s also important to point out that we’ll be using an HTTP API as our target implementation. We won’t be using an event-driven React API, a query-driven GraphQL API, or a function-driven gRPC API. This decision to create an HTTP-based API is our starting point. We could imagine that someone at BigCo, where the Onboarding API will be built, has decided this for us. In other cases, the API style might be determined by a customer, by some other team in the company, or just by ourselves. Deciding on the target is the start of turning our ALPS description into an implementation definition.

We have already designed our API and generated our WSD. We then translated that diagram into an ALPS description. Now, we can use both of them as a reference when laying out our HTTP-style API.

HTTP specifications of Onboarding API

A key element in HTTP-style APIs is a focus on individual resources (identified by a URL) and the ability to read and write their states (the data properties associated with each resource). When we lay out our HTTP implementation, we need to declare our resources and determine which properties are displayed and/or edited for each of them.

The following is the output of our WSD diagram: