Join Keith Casey for an in-depth discussion in this video Overview of HTTP, part of Effective Design of RESTful APIs.
Now that we've modeled our API successfully, we need to get familiar with the medium we're actually using. HTTP is a great tool in that it underlies the entire web, and is well understood by most clients and tools out there, which is the foundation on which REST is built. Unfortunately, it can lead to a bit of of a misunderstanding. It's worth stating clearly that REST is not a standard. There are all kinds of debates about what is RESTful, RESTish, and a variety of other concepts. Honestly, don't worry about it. While there are patterns for things like URLs and XMLs/JSON payloads, there's not a formal requirement on how they are structured, even the payloads that go along with them.
That said, it's worth remembering that REST is a generally agreed upon set of principles or constraints. It's not a specification, which is great. It gives us a ton of flexibility. The downside is that there's not always a right answer to everything. Of course, that said, the REST concepts are based on a set of standards. For better understanding, I use a simple analogy. SOAP is like a mortgage. Giving a mortgage is a detailed process. It requires a huge amount of documentation up front. There are detailed scenarios laid out to resolve any sort of error situations or specific circumstances that come along.
As an alternative, REST is like borrowing ten dollars from a friend for lunch. There's no documentation up front. There are no hard and fast requirements. The agreement to pay back the friend is implicit, not explicit. You may pay them back in a variety of ways. Maybe you give them ten dollars tomorrow. Maybe you buy them lunch, or whatever. The flexibility is great, but if you're not careful, it puts some ambiguity into the mix. This ambiguity must be figured out and resolved. One of the official standards in the mix when you discuss REST concepts is the backbone of the internet, or simple HTTP.
Fundamentally, this is a good thing. HTTP is well understood protocol that is both simple and powerful in its implementation. Every HTTP request and response has two parts. The headers and the payload. The payload is the HTML, JSON, XML, or whatever comes back that you can view and process. If it's just HTML, it's usually read to the screen for the user. Payloads are generally well understood, so in the next video, we'll skip directly into understanding the headers.
- The three approaches to adding an API
- Modeling tips
- Creating and grouping API methods
- Mapping activities to verbs and actions
- Validating your API
- Working with HTTP headers and response codes
- Layered systems
- Creating a uniform interface