REST APIs must be hypertext-driven——Posted by Roy T. Fielding
2016-04-10 09:47
295 查看
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
Mon 20 Oct 2008
Posted by Roy T. Fielding under
software architecture,
web architecture
I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is theSocialSite
REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot
be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?
API designers, please note the following rules before calling your creation a REST API:
A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc. In general, any protocol element
that uses a URI for identification must allow any URI scheme to be used for the sake of that identification.[Failure here implies that identification is not separated from interaction.]
A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field. Workarounds
for broken implementations (such as those browsers stupid enough to believe that HTML defines HTTP’s method set) should be defined separately, or at least in appendices, with an expectation that the workaround will eventually be obsolete.[Failure here
implies that the resource interfaces are object-specific, not generic.]
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up
for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).[Failure
here implies that out-of-band information is driving interaction instead of hypertext.]
A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct
appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations.[Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific
standard, which is the data-oriented equivalent to RPC’s functional coupling].
A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and
invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names.[ditto]
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might
use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions
may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand).[Failure here implies that out-of-band information is driving interaction instead
of hypertext.]
There are probably other rules that I am forgetting, but the above are the rules related to the hypertext constraint that are most often violated within so-called REST APIs. Please try to adhere to them or choose some other buzzword
for your API.
Mon 20 Oct 2008
Posted by Roy T. Fielding under
software architecture,
web architecture
I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is theSocialSite
REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot
be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?
API designers, please note the following rules before calling your creation a REST API:
A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc. In general, any protocol element
that uses a URI for identification must allow any URI scheme to be used for the sake of that identification.[Failure here implies that identification is not separated from interaction.]
A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field. Workarounds
for broken implementations (such as those browsers stupid enough to believe that HTML defines HTTP’s method set) should be defined separately, or at least in appendices, with an expectation that the workaround will eventually be obsolete.[Failure here
implies that the resource interfaces are object-specific, not generic.]
A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up
for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types).[Failure
here implies that out-of-band information is driving interaction instead of hypertext.]
A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct
appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations.[Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific
standard, which is the data-oriented equivalent to RPC’s functional coupling].
A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and
invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names.[ditto]
A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might
use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions
may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand).[Failure here implies that out-of-band information is driving interaction instead
of hypertext.]
There are probably other rules that I am forgetting, but the above are the rules related to the hypertext constraint that are most often violated within so-called REST APIs. Please try to adhere to them or choose some other buzzword
for your API.
相关文章推荐
- Linux内核分析第七周———可执行程序的装载
- java中的常量
- 02.Java 集合 - ArrayList
- LVS原理详解
- 体检套餐
- hihoCoder 九十二周 数论一·Miller-Rabin质数测试 (数论 筛素数)
- WPF 绑定中的TargetNullValue
- 实验七:Linux内核如何装载和启动一个可执行程序
- 技术人员如何创业《四》- 打造超强执行力团队(转载)
- ACM总结——最长公共子序列 & 最长不减(不增)子序列
- hdu 5661
- 技术人员如何创业《三》- 合伙人的分工(转载)
- 技术人员如何创业《二》- 合伙人的模式(转载)
- Java中的Integer、Long等实例的比较
- struts标签不显示
- hadoop架构
- C++:类的语法错误 error c2533:constructors not allowed a return type(构造函数不允许返回一个类型)
- Nginx Rewrite的应用-根据访问平台做简单跳转
- PAT乙级1010-月饼
- hdu 5662