restful 接口开发规范（RESTfulAPIdesignguide）
需积分: 50 21 浏览量
2019-02-01
15:36:55
上传
评论
收藏 13KB PDF 举报
RESTful API design guide
2018-03-01 Version 4 added bad examples
RESTful API design guide
RESTful introduction
Representational state transfer (REST) or RESTful web services are a way of providing interoperability between computer systems on the
Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of using aWeb resources
uniform and predefined set of .stateless operations
Resource-Oriented
Each RESTful URI represents an entity on web. And operations on the resource should be done by the CRUD HTTP methods GET, POST, PUT,
DELETE and so on. This also means no verbs can be seen in URI.
Stateless
Each request from any client contains all the information necessary to service the request, and session state is held in the server.
BTSMED RESTful API design guide
Here are some basic guides from best practices in the industry which includes design for version, endpoint, request, response. The guide is
based on .https://confluence.int.net.nokia.com/pages/viewpage.action?spaceKey=NE3S&title=REST+Guidelines
URI - API module name
API module name indicates the scope and vision for the API. Such as cm, fm, swm etc.
URI - Version
URI Versioning – version the URI space using version indicators.
Version should be put right after the host and API module name (if applicable):
Example:
http://localhost:9093/api/cm/v1/services/...
URI - Resource Name
Resource name is a hierarchically organized entity names separated by slashes. Following are some good design practices from industry:
Use noun for resource name
Use plural for resource name
Use lower case in naming convention
No underscores '_' in URI, replace them with hyphens '-'
Use HTTP method to remove CRUD verbs in URI
Keep consistency
Use path variables to identify specific resource (such as {planId})
Use query parameters at the end of URI to narrow down the result list
No forward slash at the end of URI
HTTP Method
The CRUD actions and operations on a resource should be done by HTTP methods with appropriate request, response and http status code. All
contents in request or response body mentioned below should be in JSON format.
资源评论
