RESTful API的声明方式

Architectural Styles and the Design of Network-based Software Architectures, by Roy Thomas Fielding

体系结构风格与基于网络的软件体系结构设计
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

REST Representational State Transfer

His painting went through both representational and abstract periods.

Distributed Hypermedia System
HATEOAS Hypermedia as the engine of application state

• Give every "thing" an ID
• Link things together
• Use standard methods
• Resources with multiple representations
• Communicate statelessly

Representation 资源呈现
Representational State 可被呈现的状态
Representational State Transfer 可被呈现的状态转换

RESTful Web Services, by Lenoard Rechardson & Sam Rubby

ROA: Resource Oriented Architecture

   1: <movie>
   2:   <name>魔鬼代言人</name>
   3:   <genre>剧情|悬疑|惊悚</genre>
   4:   <directors>
   5:     <add ref="http://www.artech.com/directors/taylor-hackford">泰勒.海克福德</add>
   6:   </directors>
   7:   <starring>
   8:     <add ref = "http://www.artech.com/actors/al-pacino">阿尔.帕西诺</add>
   9:     <add ref = "http://www.artech.com/actors/keanu-reeves ">基诺.李维斯</add>
  10:   </starring>
  11:   <supportingActors>
  12:     <add ref = "http://www.artech.com/actors/charlize-theron ">查理兹.塞隆</add>
  13:     <add ref = "http://www.artech.com/actors/jeffrey-jones ">杰弗瑞.琼斯</add>  
  14:     <add ref = "http://www.artech.com/actors/connie-nielsen">康尼.尼尔森</add>  
  15:   </supportingActors>
  16:   <scriptWriters>
  17:     <add ref = "http://www.artech.com/scriptwriters/jonathan-lemkin">乔纳森•莱姆金</add>
  19:     <add ref = "http://www.artech.com/scriptwriters/tony-gilroy">托尼•吉尔罗伊 </add>  
  20:   </scriptWriters>
  21:   <language>英语</language>
  22:   <poster ref = "http://www.artech.com/images/the-devil-s-advocate"/>
  23:   <story>...</story>
  24: </movie>

  1: public class RoleService
   2: {
   3:     public IEnumerable<string> GetAllRoles();
   4:     public void CreateRole(string roleName);
   5:     public void DeleteRole(string roleName);
   6:  
   7:     public void AddRolesInUser(string userName, string[] roleNames);
   8:     public void RemoveRolesFromUser(string userName, string[] roleNames);
   9: }

Role Assignment 角色委派

   1: public class RolesService
   2: {
   3:     public IEnumerable<string> Get();
   4:     public void Create(string roleName);
   5:     public void Delete(string roleName);
   6: }
   7:  
   8: public class RoleAssignmentsService
   9: {
  10:     public void Create(RoleAssignment roleName);
  11:     public void Delete(RoleAssignment roleName);
  12: }

   1: public class ResourceService
   2: {
   3:     public IEnumerable<Resource>[] Get();
   4:     public void Post(Resource resource); 
   5:     public void Put(Resource resource);
   6:     public void Patch (Resource resource);
   7:     public void Delete(string id);
   8:     public void Get(string id);
   9:     public void Head(string id);
  10:     public void Options();
  11: }

   1: PUT http://www.artech.com/employees/300357 HTTP/1.1
   2: ...
   3:  
   4: <employee>
   5:   <id>300357</id> 
   6:   <name>张三</name>
   7:   <gender>男<gender>
   8:   <birthdate>1981-08-24</birthdate>
   9:   <department>3041</department>
  10: </employee>

   1: POST http://www.artech.com/employees HTTP/1.1
   2: ...
   3:  
   4: <employee>
   5:   <name>张三</name>
   6:   <gender>男<gender>
   7:   <birthdate>1981-08-24</birthdate>
   8:   <department>3041</department>
   9: </employee>

Side Effect 边界效应

Idempotent 幂等性

Affinty 亲和度

HTTP: The Definitive Guide, by David Gourley,...
TCP/IP Illustrated (Volumn 1: The Protocol), by W. Richard Stevens

http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html