restful 风格接口设计

restful

Representational State Transfer 表现层状态转换

用资源名词复数表示资源，以HTTP方法表示操作

以公司和员工为例

• 创建一个公司: POST /api/v1.0/companies

• 获取公司列表: GET /api/v1.0/companies

• 获取某个公司: GET /api/v1.0/companies/:id

• 删除某个公司: DELETE /api/v1.0/companies/:id

• 更新某个公司信息: PUT /api/v1.0/companies/:id

• 获取公司下的员工们: GET /api/v1.0/companies/:company_id/employees

• 创建一个员工: POST /api/v1.0/companies/:company_id/employees

• 获取某个员工信息: GET /api/v1.0/companies/:company_id/employees/:employee_id

• 删除某个员工信息: DELETE /api/v1.0/companies/:company_id/employees/:employee_id

• 更新某个员工信息: PUT /api/v1.0/companies/:company_id/employees/:employee_id

排序，过滤，分页

排序

可以在GET URL中指定要排序的字段以及顺序
GET /api/v1.0/companies?field=created_at&order=desc

过滤

按照 cit和 location过滤
GET /api/v1.0/companies?city=北京&location=望京

分页

指定offset和limit
GET /api/v1.0/companies?offset=0&limit=100

GET /api/v1.0/companies?offset=99&limit=100