API design and cross-border collaboration - part two

Recap

In our last blog post, we discussed how API design principles can enhance remote team collaboration. Clear communication, structured "collaboration contracts," and a focus on reliability were key takeaways. Today, we’ll delve deeper into API design concepts, such as REST, to explore how they can further strengthen teamwork across borders.

Introduction to REST

Why are modern APIs the the way they are? The largest driver is scale. One of the best scaling and user friendly designs is REST—representational state transfer. Taking our last demo as an example, this means separating the request of asking ntfy to send a "pancake notification", the version stored on ntfy’s servers, and the one displayed on your phone. For example, the message "It’s pancake time! 🥞" is processed multiple times before appearing in your notification center.

REST has become the standard for web-scale data formats and transfer because it relies on pre-existing fundamental web commands like HTTP, each communication is self contained, and it is easy to adopt. Let's briefly discuss what HTTP commands do.

What patterns emerge in APIs like Stripe and Shopify? Their design focuses on specific, targeted, and well-defined operations. Notice how their HTTP actions align with basic data changes, making their services precise and reliable.

This table lists the main HTTP actions and how they work:

They are called request methods because a 'server' like the ntfy server gets requests from another computer, like ours, which it acts on. As in our ntfy example above, we use cURL to leverage HTTP to make changes in ntfy's data. Our computer started the discussion so it is called the client in this case, but we could make it listen to requests too and act as a server. The server needs to make sure it understands requests to it, makes the correct data changes, and acknowledge all this as soon as it can.

Acknowledgement is key to closing the loop, and you might have seen some famous server responses before, like 404: not found as one of the many types of responses in HTTP.

Among the great amount of resources supporting REST, HTTP cats is a fun way to learn about server responses. Server responses are grouped in categories of hundreds like so:

Ideally, more information should be returned with the response code so the API customer can easily understand what needs to be done.

To round this up, here are the REST principles that help this design succeed and scale:

• client and server – these must be independent of each other and separated by a well defined interface

• uniform interface – all API requests for the same resource should have the same uniform resource identifier (URI). For example, when operating a 'customer' resource, these are all uniform and it is the HTTP verb that is used to signal intent :

  • POST/ v1/ customers/ :id - create a customer

  • GET/ v1/ customers/ :id - get information on customer

  • DELETE/ v1/ customers/ :id - delete customer

  • the server responses should be uniform too. for example, the GET response should let the client know how to retrieve the full list of Stripe customers if you remove the id filter

• statelessness – this means the client knows everything needed to operate on the server in one request, and so does the server.

  • This is very important for scalability: more computers running the server software can be added behind an API to scale the service without having to share context of previous client requests.

• cacheable – resources should be cached on the client side and server side, to improve performance and scalability. Caching is when you store information you already know. This saves resources and optimises for scaling, because you do not need to calculate and retrieve cached information over the internet again.

• possibility for layering – allows for security and scaling services to be placed between the client and the server, to make the service more reliable and secure, without the client or the server necessarily having knowledge of this supporting infrastructure

How to think when creating REST APIs

Design is constraint. You must create a sandbox with the right level of abstraction for your customers to solve their problems. To be a great API designer, try to get API integration experience, so you can be in your customer's shoes. If you did, a lot of what you'll read below will resonate, but if you haven't, you don't need to take it from me, take it from a standout UK institution: its Digital Service. These are their tips for API design:

• Start with your customer's needs

• Check for existing APIs and reuse or expand them if you can

• Build your API before the system powering it so you prioritise user experience, API self sufficiency, and separation of business logic from internal system actions

• Write out an API specification i.e. following OpenAPI

  • Test your assumptions with customers against the specification you wrote before committing to building an API

• Iterate on the design and decide what your live API will look like. If you change it in the future, it needs to be backwards compatible, so it's much easier to iterate on core mechanics before it is published.

Judging an API's design

To sum up, APIs can be judged on:

• range and clarity of commands accepted:

  • is the request self contained? would a third party like a firewall be able to interpret it?

  • are the commands available clear, consistent and predictable?

  • are they abstracting the business logic well enough from the internal system? This lets your customer focus on the core work that brings them value

• quality of response given

  • do users perceive it as:

    • fast?

    • precise where it needs to be? expansive where it needs to be?

    • usable. are errors easy to diagnose? is the output consistent?

• how easy is it to navigate the API without a heavy set of docs

  • can the API responses predict the next need of the user and offer steps in that direction?

  • could a machine completely navigate the API interface at runtime without external context?

REST and cross-border collaboration

In the early 2000's, Jeff Bezos issued an API mandate across Amazon, commanding every service, internal or not, to be accessible programmatically. This bold move fostered a platform-driven culture at Amazon. While I wasn’t there to measure the direct impact, the principles behind it are worth experimenting with in modern cross-border collaboration.

Imagine working with APIs. You send a request, wait for a response, and then proceed to the next step in the process. This sequential flow ensures that each step is understood before moving on. The same principle applies to human collaboration. When you communicate with someone, you cannot speed up the process; both parties must take turns exchanging information. Just like an API request, each step in communication builds on the last, and without waiting for the response, the process falls apart. Additionally, just as you can’t send more than one API request at a time (in most cases), communication between people is similarly linear—you can't "talk over" someone.

Now, imagine everyone on a shared communication line. The challenge intensifies: you can’t talk over others. Communication, in these scenarios, follows a sequential process. Let’s call this type A processing:

1. Type A: Sequential Processing: Humans handle language and step-by-step collaboration in a linear way, processing and manipulating information as symbols—much like how API interfaces trigger specific server operations.

2. Type B: Parallel and Nonlinear Processing: At the same time, humans excel at tasks like recognizing faces or multitasking during a meeting. Nonlinear thinking is also essential for creative problem-solving and forecasting complex scenarios.

Both of these are influenced by contextual understanding. Context adds depth to communication. It flavors experiences, shaping how information is interpreted and shared.

Most APIs rely on clear, step-by-step communication and so do people for collaboration. This linear handshake is necessary before more parallel processing can take place.

Some conclusions:

a) Just as an API’s success relies on well-defined inputs, outputs, and states, effective collaboration depends on shared context. You can never fully communicate the depth of an idea that exists in your mind. Without a shared understanding (or “context”), Type 1 processing—step-by-step communication—breaks down. This is why successful teams spend time building common ground, ensuring that everyone has the same context before they dive into more complex tasks. Ironically, the more of an expert you are in a subject, the more likely you are to underestimate this challenge. Success hinges on quickly building and sharing context.

b) Type 2 processing (parallel and nonlinear thought) depends on the success of type 1 processing (sequential communication). Even if you reach the right conclusions through creative thinking, you must break them down into clear, sequential steps to leverage your team effectively. It’s like conducting an orchestra: synchronization and moments of silence are as crucial as the music itself.

Just as poorly designed APIs lead to errors and inefficiencies, unclear communication can derail team collaboration. Misaligned goals and expectations are like incompatible API requests—frustrating and unproductive. Establishing shared goals is akin to designing robust APIs: it sets the foundation for clarity and alignment.

Making remote work more deliberate

Ultimately, the principles that make APIs successful—planning, abstraction, and standardization—can enhance teamwork. By adopting these approaches, individuals and teams can create scalable, efficient workflows that mirror the seamless integration of a well-designed API . You can’t duplicate yourself, but you can create systems—documents, workflows, and organizational structures—that shape how information flows within your team, making remote work more effective.

Just as APIs benefit from planning and abstraction, so does teamwork. Talking, like prototyping, is a low-cost way to refine ideas before committing.

The essence of an API—and effective communication—is simplicity in use. While APIs can be complex in their functionality, they shouldn’t be difficult to use. An API that takes too long to implement isn’t a good API, and there will always be competitors offering a more intuitive experience.

Could you collaborate effectively with another human in a completely different timezone without ever meeting them?

Deeply understand your domain. It is not an event but a lifelong process

• Embrace constraints. Design is constraint. Define and design your domain, not so you get to where can’t add any more to it, but so there is nothing more you can take away

Planning - API planning is always the most important step.

• Do you know what your goal is? How often do you review it?

  • This year?

  • This month?

  • Today?

• Do you know what kind of work you will not do? Or delegate?

  • Are your boundaries well defined?

• Do you know your customer’s goals?

• Do you know your competitor’s goals?

Clear communication - API 'contracts' clearly define how they can be used and don't hide inconsistent behavior

• How can you communicate more clearly?

• How can you communicate more regularly?

• How connected and informed do your teammates feel?

• How can you say less than all the details you know, while referring where others can find more information?

• How can you let your 'customer' reach you in terms that directly link to what is valuable to them?

• Use your domain knowledge to creatively solve your customers problems in the most intuitive way for them

Collaboration and support - APIs often require collaboration between different teams or organisations to develop, maintain, and support them.

• Do you know your teammate’s goals?

• Do you know their preferred way of collaborating?

• Do you know how best to contribute to shared goals?

• What about other teams in your organisation?

Documentation - A well-designed API must have clear, concise, and easily understood documentation to enable developers to integrate with it effectively.

• Do you have a guide to how best to deal with yourself?

  • Managers in tech often create ‘readme’ files, but you don’t have to be one to create yours. Some examples here

  • ‘Readme’ files are not universally popular. In the same vein, documentation should not be so heavy it becomes a crutch. It becomes API focused vs customer focused. It is far more important to be consistent to work with.

• Is your self documentation, your team’s documentation, and your organization’s documentation clear?

  • Do you have guidelines?

• Do you keep your documentation fresh?

Work empathetically and testing - a well-designed API should be easy to use and understand, minimising developer friction and promoting adoption.

• What assumptions am I making by communicating or acting this way?

• What happened the last time someone was confused with something I said?

• When you are communicating a new concept, method or to a new audience, how often do you test it first?

In the next article: REST maturity models and agentic API usability

We will cover

• What makes one API more RESTful than another

• The future of APIs (it's already here)

• More team collaboration principles