diff options
Diffstat (limited to 'docs/en/cowboy/2.0/guide/rest_principles')
| -rw-r--r-- | docs/en/cowboy/2.0/guide/rest_principles/index.html | 299 |
1 files changed, 151 insertions, 148 deletions
diff --git a/docs/en/cowboy/2.0/guide/rest_principles/index.html b/docs/en/cowboy/2.0/guide/rest_principles/index.html index 94ec56f5..c221d123 100644 --- a/docs/en/cowboy/2.0/guide/rest_principles/index.html +++ b/docs/en/cowboy/2.0/guide/rest_principles/index.html @@ -7,7 +7,7 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: REST principles</title> @@ -67,159 +67,162 @@ <h1 class="lined-header"><span>REST principles</span></h1> -<div class="paragraph"><p>This chapter will attempt to define the concepts behind REST
-and explain what makes a service RESTful.</p></div>
-<div class="paragraph"><p>REST is often confused with performing a distinct operation
-depending on the HTTP method, while using more than the GET
-and POST methods. That’s highly misguided at best.</p></div>
-<div class="paragraph"><p>We will first attempt to define REST and will look at what
-it means in the context of HTTP and the Web.
-For a more in-depth explanation of REST, you can read
-<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Roy T. Fielding’s dissertation</a>
-as it does a great job explaining where it comes from and
-what it achieves.</p></div>
-<div class="sect1">
-<h2 id="_rest_architecture">REST architecture</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>REST is a <strong>client-server</strong> architecture. The client and the server
-both have a different set of concerns. The server stores and/or
-manipulates information and makes it available to the user in
-an efficient manner. The client takes that information and
-displays it to the user and/or uses it to perform subsequent
-requests for information. This separation of concerns allows both
-the client and the server to evolve independently as it only
-requires that the interface stays the same.</p></div>
-<div class="paragraph"><p>REST is <strong>stateless</strong>. That means the communication between the
-client and the server always contains all the information needed
-to perform the request. There is no session state in the server,
-it is kept entirely on the client’s side. If access to a resource
-requires authentication, then the client needs to authenticate
-itself with every request.</p></div>
-<div class="paragraph"><p>REST is <strong>cacheable</strong>. The client, the server and any intermediary
-components can all cache resources in order to improve performance.</p></div>
-<div class="paragraph"><p>REST provides a <strong>uniform interface</strong> between components. This
-simplifies the architecture, as all components follow the same
-rules to speak to one another. It also makes it easier to understand
-the interactions between the different components of the system.
-A number of constraints are required to achieve this. They are
-covered in the rest of the chapter.</p></div>
-<div class="paragraph"><p>REST is a <strong>layered system</strong>. Individual components cannot see
-beyond the immediate layer with which they are interacting. This
-means that a client connecting to an intermediate component, like
-a proxy, has no knowledge of what lies beyond. This allows
-components to be independent and thus easily replaceable or
-extendable.</p></div>
-<div class="paragraph"><p>REST optionally provides <strong>code on demand</strong>. Code may be downloaded
-to extend client functionality. This is optional however because
-the client may not be able to download or run this code, and so
-a REST component cannot rely on it being executed.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_resources_and_resource_identifiers">Resources and resource identifiers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>A resource is an abstract concept. In a REST system, any information
-that can be named may be a resource. This includes documents, images,
-a collection of resources and any other information. Any information
-that can be the target of an hypertext link can be a resource.</p></div>
-<div class="paragraph"><p>A resource is a conceptual mapping to a set of entities. The set of
-entities evolves over time; a resource doesn’t. For example, a resource
-can map to "users who have logged in this past month" and another
-to "all users". At some point in time they may map to the same set of
-entities, because all users logged in this past month. But they are
-still different resources. Similarly, if nobody logged in recently,
-then the first resource may map to the empty set. This resource exists
-regardless of the information it maps to.</p></div>
-<div class="paragraph"><p>Resources are identified by uniform resource identifiers, also known
-as URIs. Sometimes internationalized resource identifiers, or IRIs,
-may also be used, but these can be directly translated into a URI.</p></div>
-<div class="paragraph"><p>In practice we will identify two kinds of resources. Individual
-resources map to a set of one element, for example "user Joe".
-Collection of resources map to a set of 0 to N elements,
-for example "all users".</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_resource_representations">Resource representations</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The representation of a resource is a sequence of bytes associated
-with metadata.</p></div>
-<div class="paragraph"><p>The metadata comes as a list of key-value pairs, where the name
-corresponds to a standard that defines the value’s structure and
-semantics. With HTTP, the metadata comes in the form of request
-or response headers. The headers' structure and semantics are well
-defined in the HTTP standard. Metadata includes representation
-metadata, resource metadata and control data.</p></div>
-<div class="paragraph"><p>The representation metadata gives information about the
-representation, such as its media type, the date of last
-modification, or even a checksum.</p></div>
-<div class="paragraph"><p>Resource metadata could be link to related resources or
-information about additional representations of the resource.</p></div>
-<div class="paragraph"><p>Control data allows parameterizing the request or response.
-For example, we may only want the representation returned if
-it is more recent than the one we have in cache. Similarly,
-we may want to instruct the client about how it should cache
-the representation. This isn’t restricted to caching. We may,
-for example, want to store a new representation of a resource
-only if it wasn’t modified since we first retrieved it.</p></div>
-<div class="paragraph"><p>The data format of a representation is also known as the media
-type. Some media types are intended for direct rendering to the
-user, while others are intended for automated processing. The
-media type is a key component of the REST architecture.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_self_descriptive_messages">Self-descriptive messages</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Messages must be self-descriptive. That means that the data
-format of a representation must always come with its media
-type (and similarly requesting a resource involves choosing
-the media type of the representation returned). If you are
-sending HTML, then you must say it is HTML by sending the
-media type with the representation. In HTTP this is done
-using the content-type header.</p></div>
-<div class="paragraph"><p>The media type is often an IANA registered media type, like
-<code>text/html</code> or <code>image/png</code>, but does not need to be. Exactly
-two things are important for respecting this constraint: that
-the media type is well specified, and that the sender and
-recipient agree about what the media type refers to.</p></div>
-<div class="paragraph"><p>This means that you can create your own media types, like
-<code>application/x-mine</code>, and that as long as you write the
-specifications for it and that both endpoints agree about
-it then the constraint is respected.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_hypermedia_as_the_engine_of_application_state">Hypermedia as the engine of application state</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The last constraint is generally where services that claim
-to be RESTful fail. Interactions with a server must be
-entirely driven by hypermedia. The client does not need
-any prior knowledge of the service in order to use it,
-other than an entry point and of course basic understanding
-of the media type of the representations, at the very least
-enough to find and identify hyperlinks and link relations.</p></div>
-<div class="paragraph"><p>To give a simple example, if your service only works with
-the <code>application/json</code> media type then this constraint
-cannot be respected (as there are no concept of links in
-JSON) and thus your service isn’t RESTful. This is the case
-for the majority of self-proclaimed REST services.</p></div>
-<div class="paragraph"><p>On the other hand if you create a JSON based media type
-that has a concept of links and link relations, then
-your service might be RESTful.</p></div>
-<div class="paragraph"><p>Respecting this constraint means that the entirety of the
-service becomes self-discoverable, not only the resources
-in it, but also the operations you can perform on it. This
-makes clients very thin as there is no need to implement
-anything specific to the service to operate on it.</p></div>
-</div>
-</div>
+<div class="paragraph"><p>This chapter will attempt to define the concepts behind REST +and explain what makes a service RESTful.</p></div> +<div class="paragraph"><p>REST is often confused with performing a distinct operation +depending on the HTTP method, while using more than the GET +and POST methods. That’s highly misguided at best.</p></div> +<div class="paragraph"><p>We will first attempt to define REST and will look at what +it means in the context of HTTP and the Web. +For a more in-depth explanation of REST, you can read +<a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Roy T. Fielding’s dissertation</a> +as it does a great job explaining where it comes from and +what it achieves.</p></div> +<div class="sect1"> +<h2 id="_rest_architecture">REST architecture</h2> +<div class="sectionbody"> +<div class="paragraph"><p>REST is a <strong>client-server</strong> architecture. The client and the server +both have a different set of concerns. The server stores and/or +manipulates information and makes it available to the user in +an efficient manner. The client takes that information and +displays it to the user and/or uses it to perform subsequent +requests for information. This separation of concerns allows both +the client and the server to evolve independently as it only +requires that the interface stays the same.</p></div> +<div class="paragraph"><p>REST is <strong>stateless</strong>. That means the communication between the +client and the server always contains all the information needed +to perform the request. There is no session state in the server, +it is kept entirely on the client’s side. If access to a resource +requires authentication, then the client needs to authenticate +itself with every request.</p></div> +<div class="paragraph"><p>REST is <strong>cacheable</strong>. The client, the server and any intermediary +components can all cache resources in order to improve performance.</p></div> +<div class="paragraph"><p>REST provides a <strong>uniform interface</strong> between components. This +simplifies the architecture, as all components follow the same +rules to speak to one another. It also makes it easier to understand +the interactions between the different components of the system. +A number of constraints are required to achieve this. They are +covered in the rest of the chapter.</p></div> +<div class="paragraph"><p>REST is a <strong>layered system</strong>. Individual components cannot see +beyond the immediate layer with which they are interacting. This +means that a client connecting to an intermediate component, like +a proxy, has no knowledge of what lies beyond. This allows +components to be independent and thus easily replaceable or +extendable.</p></div> +<div class="paragraph"><p>REST optionally provides <strong>code on demand</strong>. Code may be downloaded +to extend client functionality. This is optional however because +the client may not be able to download or run this code, and so +a REST component cannot rely on it being executed.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_resources_and_resource_identifiers">Resources and resource identifiers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>A resource is an abstract concept. In a REST system, any information +that can be named may be a resource. This includes documents, images, +a collection of resources and any other information. Any information +that can be the target of an hypertext link can be a resource.</p></div> +<div class="paragraph"><p>A resource is a conceptual mapping to a set of entities. The set of +entities evolves over time; a resource doesn’t. For example, a resource +can map to "users who have logged in this past month" and another +to "all users". At some point in time they may map to the same set of +entities, because all users logged in this past month. But they are +still different resources. Similarly, if nobody logged in recently, +then the first resource may map to the empty set. This resource exists +regardless of the information it maps to.</p></div> +<div class="paragraph"><p>Resources are identified by uniform resource identifiers, also known +as URIs. Sometimes internationalized resource identifiers, or IRIs, +may also be used, but these can be directly translated into a URI.</p></div> +<div class="paragraph"><p>In practice we will identify two kinds of resources. Individual +resources map to a set of one element, for example "user Joe". +Collection of resources map to a set of 0 to N elements, +for example "all users".</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_resource_representations">Resource representations</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The representation of a resource is a sequence of bytes associated +with metadata.</p></div> +<div class="paragraph"><p>The metadata comes as a list of key-value pairs, where the name +corresponds to a standard that defines the value’s structure and +semantics. With HTTP, the metadata comes in the form of request +or response headers. The headers' structure and semantics are well +defined in the HTTP standard. Metadata includes representation +metadata, resource metadata and control data.</p></div> +<div class="paragraph"><p>The representation metadata gives information about the +representation, such as its media type, the date of last +modification, or even a checksum.</p></div> +<div class="paragraph"><p>Resource metadata could be link to related resources or +information about additional representations of the resource.</p></div> +<div class="paragraph"><p>Control data allows parameterizing the request or response. +For example, we may only want the representation returned if +it is more recent than the one we have in cache. Similarly, +we may want to instruct the client about how it should cache +the representation. This isn’t restricted to caching. We may, +for example, want to store a new representation of a resource +only if it wasn’t modified since we first retrieved it.</p></div> +<div class="paragraph"><p>The data format of a representation is also known as the media +type. Some media types are intended for direct rendering to the +user, while others are intended for automated processing. The +media type is a key component of the REST architecture.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_self_descriptive_messages">Self-descriptive messages</h2> +<div class="sectionbody"> +<div class="paragraph"><p>Messages must be self-descriptive. That means that the data +format of a representation must always come with its media +type (and similarly requesting a resource involves choosing +the media type of the representation returned). If you are +sending HTML, then you must say it is HTML by sending the +media type with the representation. In HTTP this is done +using the content-type header.</p></div> +<div class="paragraph"><p>The media type is often an IANA registered media type, like +<code>text/html</code> or <code>image/png</code>, but does not need to be. Exactly +two things are important for respecting this constraint: that +the media type is well specified, and that the sender and +recipient agree about what the media type refers to.</p></div> +<div class="paragraph"><p>This means that you can create your own media types, like +<code>application/x-mine</code>, and that as long as you write the +specifications for it and that both endpoints agree about +it then the constraint is respected.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_hypermedia_as_the_engine_of_application_state">Hypermedia as the engine of application state</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The last constraint is generally where services that claim +to be RESTful fail. Interactions with a server must be +entirely driven by hypermedia. The client does not need +any prior knowledge of the service in order to use it, +other than an entry point and of course basic understanding +of the media type of the representations, at the very least +enough to find and identify hyperlinks and link relations.</p></div> +<div class="paragraph"><p>To give a simple example, if your service only works with +the <code>application/json</code> media type then this constraint +cannot be respected (as there are no concept of links in +JSON) and thus your service isn’t RESTful. This is the case +for the majority of self-proclaimed REST services.</p></div> +<div class="paragraph"><p>On the other hand if you create a JSON based media type +that has a concept of links and link relations, then +your service might be RESTful.</p></div> +<div class="paragraph"><p>Respecting this constraint means that the entirety of the +service becomes self-discoverable, not only the resources +in it, but also the operations you can perform on it. This +makes clients very thin as there is no need to implement +anything specific to the service to operate on it.</p></div> +</div> +</div> + + + <nav style="margin:1em 0"> |