cowboy rest

REST Flowcharts

这章节将通过一些列不同的流程图来介绍REST处理状态机。

一个请求主要有四条路线，一个是方法OPTIONS。 一个是方法GET和HEAD。一个是PUT。POST和PATCH，最后一个是DELETE。

所有的路径都是从“Start”開始。假设资源存在，除了OPTIONS路径，其它所有路径都经过“Content negotiation”而且可选“Conditional requests” 图。

红色代表引用另外的图。淡绿色表明是一个response，其它的图可能是一个回调或者是一个请求应答。这些都是Cowboy自己处。假设回调未定义，那么绿色箭头表明默认的行为。

Start

全部的请求都是从这里開始

全部的回调被连续运行来进行server。请求行。请求头的一般性进行检查。

假设有可能，那么请求的实体不会在不论什么步骤里被接收（要开发人员手动接收），当全部条件都满足时，Cowboy也仅仅是运行到PUT，POST和PATCH方法的尾部。

The known_method和allowed_methods回调返回值是一些列的方法，然后Cowboy检查请求方法是否在这些列表里面，否则终止运行。

is_authorized回调能够用来检查资源的訪问是否授权，授权也可一依据须要来决定是否被运行。假设授权失败，那么回调函数的返回值必须包括 可訪问的资源列表， 这些列表将被以 www-authenticate header 的形式发送给client。

当运行完上面的流程后。假设请求的方法是OPTIONS，那么立即会运行“OPTIONS method”图，否则将运行“Content negotiation” 图。

OPTIONS
method

这个流程图仅仅适用于OPTIONS 请求。

OPTIONS 回调能够用于加入一些关于资源的信息，如媒体类型。服务可接受的语言。可接受的方法；或者其它一些额外的信息。 虽然client不应该读取他，可是一个应答实体也能够被设置。

假设 options 回调未定义。Cowboy默认会发送一个包括可接收的方法的列表 的应答。

Content
negotiation

这个流程适用于全部的请求方法，除了OPTIONS外，在“start”后，它会紧跟着被运行。

这些步骤的目的是确定一个适当的结果发送给回client。

该请求能够包括随意的可接受的请求头；可接受的语言头。可接受的字符集头。假设存在这些头。cowboy将会解析这些头然后调用对应的回调来获得提供的内容类型，此资源语言或字符集的列表，然后。它会自己主动选择基于请求的最佳匹配。

假设回调没有被定义，那么cowboy将会选择client喜欢的content-type, language 和charset.

content_types_provied也能够返回每一种它能够接收的content-type的回调的名字。当全部的条件都满足，那么该回调仅仅会在"GET和HEAD方法"结束时被回调。

可选择的content-type,language和charset会被保存在请求对象的meta处，假设手动发送应答体。那么应该选择适当的具有代表性的这些类型。

这个流程结束后，立即接下来的是“GET和HEAD方法”的流程图或者是“PUT，POST和PATCH方法”的流程图，再或者是“DELETE方法“的流程图。主要依赖于请求方法的类型。

GET和HEAD
方法

这个流程图仅仅适用于GET和HEAD请求.

请到"Conditional request"处查看 cond step 的具体描写叙述。

当资源存在时。conditional step也是成功的。资源也可被检索到。

When the resource exists, and the conditional steps succeed, the resource can be retrieved.

Cowboy prepares the response by first retrieving metadata about the
representation, then by calling the ProvideResource callback. This is the callback
you defined for each content-types you returned from content_types_provided.
This callback returns the body that will be sent back to the client, or a fun if the body must be streamed.
When the resource does not exist, Cowboy will figure out whether the resource     existed previously,
and if so whether it was moved elsewhere in order to redirect the client to the new URI.
The moved_permanently and moved_temporarily callbacks must return the new location of the resource if it was in fact moved.

PUT，
POST， and PATCH methods

当资源存在时。第一个运行的步骤是conditional steps。假设成功而且方法是PUT，cowboy会调用 is_conflict . 这个函数函数用来解决竞争条件。如资源锁。

全部的方法都会被运行到 content_types_accepted这个步骤。

当资源不存在而且方法是PUT,那么Cowboy 将会检測冲突，然后转到 content_types_accepted步骤。假设是其它方法。Cowboy会检測资源是否已经存在，假设是这样子的话，会被定向到其它地方去。

资源真的不存在，而且方法是POST。accepted_missing_post的返回值是true,那么Cowboy会移到content_types_accepted 处。

否则，请求会在这里被终止。

假设他们都要移动，那么moved_permanently和moved_temporaily必须返回资源所在路径。