diff options
| author | Loïc Hoguin <[email protected]> | 2018-05-02 11:35:26 +0200 |
|---|---|---|
| committer | Loïc Hoguin <[email protected]> | 2018-05-02 11:35:26 +0200 |
| commit | fec98300ec9af6c8b5f3120a60f217983c451076 (patch) | |
| tree | 9772977293124e8b9b5b253e44d8c2695cddfb44 /docs/en/cowboy/2.4/guide/rest_principles/index.html | |
| parent | bfd2b6e01cbb36b0be0b3c860f5baf8d5b49fe7a (diff) | |
| download | ninenines.eu-fec98300ec9af6c8b5f3120a60f217983c451076.tar.gz ninenines.eu-fec98300ec9af6c8b5f3120a60f217983c451076.tar.bz2 ninenines.eu-fec98300ec9af6c8b5f3120a60f217983c451076.zip | |
Cowboy 2.4.0
Diffstat (limited to 'docs/en/cowboy/2.4/guide/rest_principles/index.html')
| -rw-r--r-- | docs/en/cowboy/2.4/guide/rest_principles/index.html | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/docs/en/cowboy/2.4/guide/rest_principles/index.html b/docs/en/cowboy/2.4/guide/rest_principles/index.html new file mode 100644 index 00000000..6ddb532b --- /dev/null +++ b/docs/en/cowboy/2.4/guide/rest_principles/index.html @@ -0,0 +1,313 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <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.37.1" /> + + <title>Nine Nines: REST principles</title> + + <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'> + <link href="/css/99s.css?r=1" rel="stylesheet"> + + <link rel="shortcut icon" href="/img/ico/favicon.ico"> + <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png"> + <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png"> + <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png"> + + +</head> + + +<body class=""> + <header id="page-head"> + <div id="topbar" class="container"> + <div class="row"> + <div class="span2"> + <h1 id="logo"><a href="/" title="99s">99s</a></h1> + </div> + <div class="span10"> + + <div id="side-header"> + <nav> + <ul> + <li><a title="Hear my thoughts" href="/articles">Articles</a></li> + <li><a title="Watch my talks" href="/talks">Talks</a></li> + <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li> + <li><a title="Request my services" href="/services">Consulting & Training</a></li> + </ul> + </nav> + <ul id="social"> + <li> + <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a> + </li> + <li> + <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a> + </li> + </ul> + </div> + </div> + </div> + </div> + + +</header> + +<div id="contents" class="two_col"> +<div class="container"> +<div class="row"> +<div id="docs" class="span9 maincol"> + +<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> + + + + + + + + + + + <nav style="margin:1em 0"> + + <a style="float:left" href="https://ninenines.eu/docs/en/cowboy/2.4/guide/multipart/"> + Multipart requests + </a> + + + + <a style="float:right" href="https://ninenines.eu/docs/en/cowboy/2.4/guide/rest_handlers/"> + REST handlers + </a> + + </nav> + + + + +</div> + +<div class="span3 sidecol"> + + +<h3> + Cowboy + 2.4 + + User Guide +</h3> + +<ul> + + <li><a href="/docs/en/cowboy/2.4/guide">User Guide</a></li> + + + <li><a href="/docs/en/cowboy/2.4/manual">Function Reference</a></li> + + +</ul> + +<h4 id="docs-nav">Navigation</h4> + +<h4>Version select</h4> +<ul> + + + + <li><a href="/docs/en/cowboy/2.4/guide">2.4</a></li> + + <li><a href="/docs/en/cowboy/2.3/guide">2.3</a></li> + + <li><a href="/docs/en/cowboy/2.2/guide">2.2</a></li> + + <li><a href="/docs/en/cowboy/2.1/guide">2.1</a></li> + + <li><a href="/docs/en/cowboy/2.0/guide">2.0</a></li> + + <li><a href="/docs/en/cowboy/1.0/guide">1.0</a></li> + +</ul> + +</div> +</div> +</div> +</div> + + <footer> + <div class="container"> + <div class="row"> + <div class="span6"> + <p id="scroll-top"><a href="#">↑ Scroll to top</a></p> + <nav> + <ul> + <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li> + </ul> + </nav> + </div> + <div class="span6 credits"> + <p><img src="/img/footer_logo.png"></p> + <p>Copyright © Loïc Hoguin 2012-2018</p> + </div> + </div> + </div> + </footer> + + + <script src="/js/custom.js"></script> + </body> +</html> + + |