restfulapi設(shè)計原則和規(guī)范方案(文件)
【正文】 序最重要的 REST 原則是，客戶端和服務(wù)器之間的交互在請求之間是無狀態(tài)的。要獲取這個資源，需要訪問它的URI，因此，URI就成了每一個資源的地址或獨一無二的識別符。它們分別對應(yīng)四種基本操作： GET： 用來獲取資源 POST： 用來新建資源 PUT： 用來更新資源 DELETE： 用來刪除資源? Hypermedia域名(ROOT URL)應(yīng)該盡量將API部署在專用域名之下。Github采用這種做法。在RESTful架構(gòu)中，每個URL代表一種資源（resource），所以網(wǎng)址中不能有動詞，只能有名詞，而且所用的名詞往往與代表的對象名稱對應(yīng)。如果某些動作是HTTP動詞表示不了的，你就應(yīng)該把動作做成一種資源。amount=。如果一個資源與另外一個資源有關(guān)系，使用子資源。? PUT（UPDATE）：在服務(wù)器更新資源（客戶端提供改變后的完整資源）。? HEAD：獲取資源的元數(shù)據(jù)。過濾信息（Filtering）如果記錄數(shù)量很多，服務(wù)器不可能都將它們返回給用戶。? ?limit=10：指定返回記錄的數(shù)量? ?offset=10：指定返回記錄的開始位置。order=asc：指定返回結(jié)果按照哪個屬性排序，以及排序順序。? 200 OK [GET]：服務(wù)器成功返回用戶請求的數(shù)據(jù)，該操作是冪等的（Idempotent）。? 401 Unauthorized [*]：表示用戶沒有權(quán)限（令牌、用戶名、密碼錯誤）。? 410 Gone [GET]：用戶請求的資源被永久刪除，且不會再得到的。盡量使用詳細(xì)的錯誤包裝信息：{ errors: [ { userMessage: Sorry, the requested resource does not exist, internalMessage: No car found in the database, code: 4xx, more info: } ]}返回結(jié)果（Response）服務(wù)器返回的數(shù)據(jù)格式，應(yīng)該盡量使用JSON，避免使用XML。{link: { rel: collection , href: , title: List of zoos, type: application/+json}}上面代碼表示，文檔中有一個link屬性，用戶讀取這個屬性就知道下一步該調(diào)用什么API了。Swagger是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化RESTful風(fēng)格的Web服務(wù)。與為底層編程所實現(xiàn)的接口類似，Swagger消除了調(diào)用服務(wù)時可能會有的猜測。附Swagger文件示例：{ swagger: , info: { version: , title: Swagger Petstore (Simple), description: A sample API that uses a petstore as an example to demonstrate features in the specification, termsOfService: , contact: { name: Swagger API team, foo, url: }, license: { name: MIT, url: } }, host: , basePath: /api, schemes: [ ], consumes: [ application/json ], produces: [ application/json ], paths: { /pets: { get: { description: Returns all pets from the system that the user has access to, operationId: findPets, produces: [ application/json, application/xml, text/xml, text/html ], parameters: [ { name: tags, in: query, description: tags to f
公司管理相關(guān)推薦
鄂ICP備17016276號-1