There is something to be learned from the fact that the Internet and World Wide Web work as well as they do, without having to be recompiled every morning.
This document contains notes on designing and implementing REST-ful HTTP API:s. I started writing this document simply because I felt a need to document my own slightly confused ideas about how to do REST-ful HTTP API:s. I hope it can be of value to other programmers struggling with the same issues.
Happy hacking!
Begin at the beginning and go on till you come to the end; then stop.
Alice in Wonderland
These guidelines are intended for programmers who want want to design and program systems that can interact with other systems in a distributed network environment.
In particular, the other systems in this distributed network environment may be implemented with different technologies, by different and independent organisations, with different business models and objectives and with differing release and update cycles. We also want to be able to continue to develop our system at the same time as the other systems are beeing developed whithout impacting the other systems negatively or having our system being impacted negatively by changes in the other systems.
The REST architectural style was concieved and the HTTP protocol was specified with specific intent to support the design and programming of such systems.
These guidelines are based on the following basic premises:
-
REST is an architectural style for software systems as conceived and described by Roy Fielding in chapter 5 of his dissertation Architectural Styles and the Design of Network-based Software Architectures. REST is not the software architecture for any specific system and it is not a technology or a technological standard or protocol. Actual systems that are designed and implemented in accordance with the REST architectural style can be said to be REST-ful.
-
HTTP is a technical and application level protocol. It is designed to enable and facilitate the design and implementation of systems that have the architectural style described by REST. HTTP is described in the following IETF RFC:s:
-
An achitectural style, like REST, is not a design specification or recipy for implementing systems. It is a description of a number of constraints and properties that systems can have and the emergent properties that such systems will have. To implement an actual system with a specific architectural style requires programmers to still make all practical design and implementation decisions regarding which technical protocols and standards to use as well as how to actually write the software.
-
An application level protocol, like HTTP, is not a technical specification of a specific system. It is a specification of how different applications should interact, but not of what data should be exchanged or when it should be exchanged. Therefore developers of a specific system that uses HTTP have to make, as always, all the decisions regarding that system’s use of HTTP and they have to actually program the system. Also, just using HTTP, does not mean that a system becomes REST-ful. Developers need to understand REST and the emergent properties of that architectural style and construct their system using HTTP as a tool to achieve those properties.
-
The Unix Philosophy as described in Basics of the Unix Philosophy.[7] by Eric S. Raymond, is good.
-
It would be nice to have a set of practical guidelines for using HTTP to design and implement HTTP API:s that enable systems using the HTTP API to be REST-ful.
-
In the end we always have to think, invent and write code!
The ambition of these guidelines is to use the REST-architectural style together with the Unix philosophy as a basis for a set of practical design and implementation choices for HTTP API:s that are REST-ful but, equally important, pragmatic and simple.
This document is organized into a number of sections, each dealing with a particular aspect of designing and implementing REST-ful HTTP API:s.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent