It doesn’t usually take too long, once clients start using an HTTP API, for the developers of the API to realize they did something less than ideal in their resource representations. As discussed in the post about representations, this is where versioning comes in. Defining different versions, however, is only half of the story. Clients and servers need to be able to agree on the versions they should use when communicating with each other. That’s where HTTP Content Negotiation (conneg) comes in.

“Event sourcing”, “CQRS”, or just plain “messaging” - it has been years since I’ve talked to a developer working on a network-exposed (usually via HTTP) service without these coming up within the initial discussion. Over the years it has become an almost doctrinal position that services need to be emitting messages and that those messages must go through a message broker (e.g., RabbitMQ, Kafka, or some cloud-provider messaging system). Yet, such systems can be incredibly complicated to deploy, run, scale, and diagnose. Additionally, developers often believe that certain behaviors (e.g., only-once delivery, absolute ordering) are present and guaranteed in message brokers when, in fact, they are not.

At the core of HTTP is the notion of resources and representations. In this post I’ll take a deep dive into each as well as discuss some implementation details that are important to consider when implementing an HTTP API. My next post will then discuss how some of the functionality and recommendations described here are used within the HTTP requests and responses in order to get some desirable behavior.

One thing that has made HTTP the go-to choice for application protocols is that its basic semantics are very straightforward. However, this simplicity has also led a lot of developers make explicit or implicit assumptions about how those basic building blocks work. In this post, I want to look at some of those potential assumptions.

As developers we’ve been making HTTP APIs^* almost since the moment HTTP started to see adoption; think of CGI scripts written in Perl or PHP (or don’t imagine it if you want to avoid the nightmare of those good-old-days). In that time we’ve learned an awful lot about improving the structure of our code and the associated, language-specific (e.g., Java, Ruby, Go) APIs. However, it doesn’t feel like we’ve made similar progress with our HTTP APIs. So, in this series of posts I want to take a deeper dive into various aspects of HTTP APIs and proffer some opinions on how we can do better.

How many of us have heard that “soft skills”, “communication”, “teamwork” and the like are “critical”, “the most important thing”, or “just as important as your technical skills”? Or perhaps from management you’ve heard that “people are our most important resource”, “we want everyone to flourish”, and “bring your whole self to work”? I suspect nearly all of us. Now, look around and count up all the time your peers, management, and company spends having well informed discussion and training on skills really meant to address/advance these goals. I bet that number is much smaller than you’d expect for something that is “the most important thing”. So, why the disconnect and what would we do if we actually wanted this to be true? My thoughts around these questions are what I’ll be discussing in this “Interpersonal Skills” series.