So you want to build an API — now what?

Now, we get to work. If you’re going to accomplish your ambitious mission, there are quite a few key API design considerations you will need to know along the way. Before you get started, let’s talk what impacts Design and Design thinking could have on the development of your API. As a developer and seasoned veteran, there is a lot to share, so we’ll keep it as brief.

Design Thinking is more than just a concept

At it’s core, Design thinking is a methodology of solving complex problems to uncover solutions. In order to have a design mindset, developers need to switch from being problem-focused to focusing on future outcomes.

The Interaction Design Federation has a unique perspective and breakdown of this methodology.

As mentioned in the article, in this five-stage model, proposed by the Hasso-Plattner Institute of Design at Stanford (, it is easy to see how it could be applied to designing anything from products to architecture. As developers, iteration is important and Design Thinking could help inform more than just the front end, user facing features of our applications.

Empathy is crucial to a human-centred design process such as Design Thinking, and empathy allows design thinkers to set aside his or her own assumptions about the world in order to gain insight into users and their needs.

Regardless of where you work in the tech stack, this statement remains true.

Design from the inside out

Let’s be honest, it can be difficult to know where to start. However; you can gain a lot of insight from other developers. If you are a developer new to building APIs or a seasoned pro, you don’t have to attend the next stuffy dev conference in Siberia to make sense of everything.

Here is a short list:

  1. Security & Privacy: Simple, secure token based authentication is a great start. OAuth 2 + SSL are also really great options. Understanding the key differences between your security options can help shape future development.
  2. Adoption: Keep it simple and easy for developers. In other words, make it as easy as possible for people to sign up. Provide language specific libraries so that specific groups of developers know where to go to find relevant information. You don’t need to reinvent REST, SOAP, or JSON to accomplish your goal.
  3. Documentation: Four words — Document all the things. If you want people to use your API, it’s important to provide straight forward, easily digestible documentation. In truth, documentation gets the most references and social shares. Make it cute!

Microservices & APIs: Your Design depends on it

At this point, the badger is out of the bag. In order for microservices to be able to function within an application, the components must be able to interact with each other. There are two design characteristics we’d like to get at the top of your list.

  1. Message-oriented: Typically, Designers have thought of “object oriented” approaches, but recent trends have focused on becoming more message oriented. This approach will also make it easier to refactor later on.
  2. Hypermedia-driven: Currently, there is a lack of tooling and support for hypermedia APIs. However; this area could show more promise in the future and could be something to investigate as you dive deeper into API Design for microservices.

Design: Two Ways

In developing your application, you have a lot of choices about how to get information from each endpoint. Let’s look at an interesting and straightforward example.

Our revenue team decides that they would like to start a new loyalty program to boost engagement. From a technical perspective, this business objective means that we need to start tracking orders by the customer in order.

One easy way to do this is to add a new customer resource, but how do we link orders with customers?

Currently, there is a division among REST practitioners on how to associate resources. Let’s take a quick example.

On one hand, hierarchy could expand producing endpoints like:

/customers/6/orders (of customer #6's orders), and /customers/6/orders/3 (for customer #6's third order).

On the other hand, you could design it differently by including the relevant details in the data for a resource. In this example, creating an order requires a customer_id field is sent with order information.

Here is the visual:

POST /customers/6/orders/4
"material": ["leather"]

As you can tell, this is much different than something that looks closer to:

POST /orders/4
"material": ["leather"]
GET /customers/6
"name": "Cheeky Little Bastard"

As a matter of fact, there is no silver bullet when it comes to choosing which one is the right one. The most important aspect is understanding why you would choose one over the other and what advantage it could bring to your architecture.

Recently posted on our blog at and includes code examples to demonstrate concepts.

Editor’s note:

We’re extremely interested in how we can apply typical Design Thinking concepts to backend infrastructure. When you start with the user’s in mind, you always come out on top. Therefore, it is easy to imagine why design pioneers could teach us (developers) so many new things.

Also important note: Cheeky Little Bastard or “CLB” is the name of our beloved Honey Badger mascot. So hold on to those nice graphite pens, because there will be a test later!

  • Sign up for our private beta — your feedback helps prioritize our roadmap with the most value realized within the shortest amount of time
  • Learn about the inaugural feature set we’re striving for to make APIs repeatedly fast, easy and manageable as you evolve through the API lifecycle itself.
  • Sign up for the latest development on APIs and microservices.