Difference between revisions of "APIStyleGuide"
(Created page with " == OpenStack APIs REST Style Guide == API Change Guidelines") |
(→OpenStack APIs REST Style Guide) |
||
| Line 5: | Line 5: | ||
[[APIChangeGuidelines|API Change Guidelines]] | [[APIChangeGuidelines|API Change Guidelines]] | ||
| + | |||
| + | === Introduction === | ||
| + | |||
| + | REST (REpresentional State Transfer) is a distributed computing style formalized by Roy Fielding in his doctoral dissertation. Fielding studied the architectural successes of the web and generalized his findings into a set of design principles that can be applied to other distributed hypermedia systems. | ||
| + | |||
| + | REST proposes several principles including: | ||
| + | |||
| + | |||
| + | * Each resource is addressable by a URI | ||
| + | * Resources are manipulated via their representations (e.g. XML, HTML, JSON, YAML etc.) | ||
| + | * A uniform interface is exposed for all resources (GET, PUT, POST, DELETE etc. in the case of HTTP) | ||
| + | * Messages are self-descriptive - i.e. each message contains everything necessary for a stateless server to process it | ||
| + | * Hypermedia as the engine of application state (HATEOAS) - state transitions (e.g. changing a resource's state or examining a related resource) is driven by the hypermedia representation of the resource itself | ||
| + | |||
| + | By applying these principles to web services in general, it is hoped that web services will gain some of the desirable properties of the web such as horizontal scalability, de-coupled clients and servers, reduced latency through the use of proxies and real interoperability. | ||
| + | |||
| + | Another very real feature of RESTful APIs is their simplicity and familiarity of use. With any RESTful API, it should be relatively trivial to point a simple client (e.g. curl in a shell script) at a URI for the API and quickly build something useful. This makes a refeshing change from heavyweight middleware frameworks such as CORBA or WS-*. | ||
Revision as of 19:29, 16 June 2014
OpenStack APIs REST Style Guide
Introduction
REST (REpresentional State Transfer) is a distributed computing style formalized by Roy Fielding in his doctoral dissertation. Fielding studied the architectural successes of the web and generalized his findings into a set of design principles that can be applied to other distributed hypermedia systems.
REST proposes several principles including:
- Each resource is addressable by a URI
- Resources are manipulated via their representations (e.g. XML, HTML, JSON, YAML etc.)
- A uniform interface is exposed for all resources (GET, PUT, POST, DELETE etc. in the case of HTTP)
- Messages are self-descriptive - i.e. each message contains everything necessary for a stateless server to process it
- Hypermedia as the engine of application state (HATEOAS) - state transitions (e.g. changing a resource's state or examining a related resource) is driven by the hypermedia representation of the resource itself
By applying these principles to web services in general, it is hoped that web services will gain some of the desirable properties of the web such as horizontal scalability, de-coupled clients and servers, reduced latency through the use of proxies and real interoperability.
Another very real feature of RESTful APIs is their simplicity and familiarity of use. With any RESTful API, it should be relatively trivial to point a simple client (e.g. curl in a shell script) at a URI for the API and quickly build something useful. This makes a refeshing change from heavyweight middleware frameworks such as CORBA or WS-*.
