用于记录RESTful API的标准方法 [英] Standard methods for documenting a RESTful API

问题描述

我正在为新的内部Web服务编写一个用于RESTful API的规范。这不是很长，相当简单，但即使如此，这是我第一次使用严格的REST（而不是为了实际的原因作弊 - 避免 PUT 和 DELETE ，因为它们是PHP的痛苦等等）。我想知道是否有任何标准的方法或最佳做法来记录一个REST界面？我希望团队的其余成员能够一目了然，而对于任何想要编写客户端的人来说，不用理解底层代码就可以这样做。

I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code.

推荐答案

在Roy的帖子中，这里他指出

In Roy's post here he states

REST API应该花费几乎所有
的描述性努力来定义
媒体类型用于表示
资源和驾驶应用程序
状态，或定义扩展
关系名称和/或
现有$ b的超文本启用标记$ b标准媒体类型。花费
的任何努力描述了什么方法用于什么
感兴趣的URI应该是完全
定义在媒体类型
的
处理规则的范围内（和在大多数情况下，现有媒体类型已经定义了
）。

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).

这篇关于用于记录RESTful API的标准方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！