New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job...
Transcript of New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job...
![Page 1: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/1.jpg)
www.twosigma.com
Principles of REST API Design
May 19, 2017
Presented By: Amy Wasik
Two Sigma Investments, LP
Important Legal Information:
This document is being distributed for informational and educational purposes only and is not an offer to sell or the solicitation of an offer to buy any securities or other instruments. The information contained herein is not intended to provide, and should not be relied upon for investment advice. The views expressed herein are not necessarily the views of Two Sigma Investments, LP or any of its affiliates (collectively, “Two Sigma”). Such views reflect significant assumptions and subjective of the author(s) of the document and are subject to change without notice. The document may employ data derived from third-party sources. No representation is made as to the accuracy of such information and the use of such information in no way implies an endorsement of the source of such information or its validity.
The copyrights and/or trademarks in some of the images, logos or other material used herein may be owned by entities other than Two Sigma. If so, such copyrights and/or trademarks are most likely owned by the entity that created the material and are used purely for identification and comment as fair use under international copyright and/or trademark laws. Use of such image, copyright or trademark does not imply any association with such organization (or endorsement of such organization) by Two Sigma, nor vice versa.
![Page 2: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/2.jpg)
Software Architecture
May 19, 2017
Single Server
Services
REST Services
![Page 3: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/3.jpg)
Our Application
May 19, 2017
Application
Job Job Job Job
Host
![Page 4: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/4.jpg)
Our Application
May 19, 2017
Application
Job Job Job Job
Host
Application
Job Job Job Job
Host
Application
Job Job Job Job
Host
Application
Job Job Job Job
Host
Application
Job Job Job Job
Host
Application
Job Job Job Job
Host
Application
Job Job Job
Host
Application
Job Job Job Job
Host
![Page 5: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/5.jpg)
Our Application
May 19, 2017
Application
Job Job Job Job
Host
Monitor Monitor
Host Host
![Page 6: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/6.jpg)
Our Application
May 19, 2017
Client API
Client Client Client
Host
Host Host Host
Scheduler
Job Job Job Job
Host
Monitor Monitor
Host Host
![Page 7: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/7.jpg)
Software Architecture
May 19, 2017
Single Server
Services
REST Services
![Page 8: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/8.jpg)
Services Architecture
May 19, 2017
• Low Coupling
• Maintainable
• Interoperable
• Language Agnostic
• Shareable
• Scalable
• Resilient
![Page 9: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/9.jpg)
Services Architecture
May 19, 2017
• Low Coupling
• Maintainable
• Interoperable
• Language Agnostic
• Shareable
• Scalable
• Resilient
Client API
Client Client Client
Host
Host Host Host
Scheduler
Job Job Job Job
Host
Monitor Monitor
Host Host
![Page 10: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/10.jpg)
Services Architecture
May 19, 2017
• Low Coupling
• Maintainable
• Interoperable
• Language Agnostic
• Shareable
• Scalable
• Resilient
Client API
Client Client Client
Host
Host Host Host
Scheduler
Job Job Job Job
Host
Monitor Monitor
Host Host
![Page 11: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/11.jpg)
Services Architecture
May 19, 2017
• Low Coupling
• Maintainable
• Interoperable
• Language Agnostic
• Shareable
• Scalable
• Resilient
High-level
Javascript
Low-level
Client API
Client Client Client
Host
Host Host Host
Scheduler
Job Job Job Job
Host
Monitor Monitor
Host Host
![Page 12: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/12.jpg)
Services Architecture
May 19, 2017
• Low Coupling
• Maintainable
• Interoperable
• Language Agnostic
• Shareable
• Scalable
• Resilient Application 2
Client API
Client Client Client
Host
Host Host Host
Scheduler
Job Job Job Job
Host
Monitor Monitor
Host Host
![Page 13: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/13.jpg)
Services Architecture
May 19, 2017
• Low Coupling
• Maintainable
• Interoperable
• Language Agnostic
• Shareable
• Scalable
• Resilient
Client API
Client Client Client
Host
Host Host Host
Scheduler
Host
Job Job Job
Host
Monitor Monitor
Host
![Page 14: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/14.jpg)
Services Architecture
May 19, 2017
• Low Coupling
• Maintainable
• Interoperable
• Language Agnostic
• Shareable
• Scalable
• Resilient
Client API
Client Client Client
Host
Host Host Host
Scheduler
Job Job Job Job
Host
Monitor Monitor
Host Host
![Page 15: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/15.jpg)
Communication
May 19, 2017
Single Server:
Local API Method Calls
Services:
Inter-process Communication
(IPC)
![Page 16: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/16.jpg)
Inter-Process Communication (IPC)
May 19, 2017
• Remote Procedure Calls (RPC)
• Use a library to convert local calls to remote ones
public interface Jobsystem {
Job createAJob(JobDetails details);
void submitJob(Job j);
List<Job> getJobs(String namePattern);
List<Job> getMyJobs(String user);
List<Job> getJobsOther(String query);
Job getJob(int id);
void updateJob(JobDetails details);
}
![Page 17: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/17.jpg)
Software Architecture
May 19, 2017
Single Server
Services
REST Services
![Page 18: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/18.jpg)
REST Architecture
May 19, 2017
Additional Constraints Benefits
Stateless Scalability
• Representational State Transfer (REST)
![Page 19: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/19.jpg)
REST Architecture
May 19, 2017
Additional Constraints Benefits
Stateless Scalability
Cacheable Increased Capacity
• Representational State Transfer (REST)
![Page 20: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/20.jpg)
REST Architecture
May 19, 2017
Additional Constraints Benefits
Stateless Scalability
Cacheable Increased Capacity
Layered Low Coupling/Interoperability
• Representational State Transfer (REST)
![Page 21: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/21.jpg)
REST Architecture
May 19, 2017
https://martinfowler.com/articles/richardsonMaturityModel.html
4 Levels of Adherence Benefits
0 – HTTP Transport
1 – Resource Oriented Design
2 – HTTP Verbs as actions on resources
3 – Hypertext as the Engine of Application State (HATEOAS)
• Representational State Transfer (REST)
• API Constraints
![Page 22: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/22.jpg)
REST Architecture
May 19, 2017
https://martinfowler.com/articles/richardsonMaturityModel.html
4 Levels of Adherence Benefits
0 – HTTP Transport Standard Interface
1 – Resource Oriented Design Easier-to-Use API
2 – HTTP Verbs as actions on resources Complete API
3 – Hypertext as the Engine of Application State (HATEOAS) Easy-to-Learn API
• Representational State Transfer (REST)
• API Constraints
![Page 23: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/23.jpg)
REST Level 0
May 19, 2017
HTTP Transport
Readable object encoding (typically JSON)
Standard URI format
![Page 24: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/24.jpg)
Level 0: RPC over HTTP
May 19, 2017
public interface Jobsystem {
Job createAJob(JobDetails details);
void submitJob(Job j);
List<Job> getJobs(String namePattern);
List<Job> getMyJobs(String user);
List<Job> getJobsOther(String query);
Job getJob(int id);
void updateJob(JobDetails details);
}
GET http://example.com/createAJob?name=t&...
GET http://example.com/submitJob?id=123
GET http://example.com/getJobs?name=test
GET http://example.com/getMyJobs?user=me
GET http://example.com/getJobs?query=...
GET http://example.com/getJob?id=123
GET http://example.com/updateJob?id=123&
![Page 25: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/25.jpg)
Level 0: RPC over HTTP
May 19, 2017
GET http://example.com/createAJob?name=t&user=userA...
HTTP/1.1 200 OK
[other headers]
{ "id": 123
}
GET http://example.com/submitJob?id=123
HTTP/1.1 200 OK
[other headers]
{ "error" : "no permission"
}
![Page 26: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/26.jpg)
REST Level 1
May 19, 2017
Resource Oriented Design
• Divide and conquer
• Easy to understand and navigate API
Standard URI Format
• /{resource}
• /{resource}/{resource-id}
• /{resource}/{resource-id}/{sub-resource}
• /{resource}/{resource-id}/{sub-resource}/{sub-resource-id}
![Page 27: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/27.jpg)
Object Oriented Design
May 19, 2017
GET http://example.com/createAJob?name=
GET http://example.com/submitJob?id=12
GET http://example.com/getJobs?name=
GET http://example.com/getMyJobs?user=
GET http://example.com/getJobs?query=
GET http://example.com/getJob?id=123
GET http://example.com/updateJob?id=123
GET http://example.com/jobs/create?name=t&user=me
GET http://example.com/jobs/get?name=test
GET http://example.com/jobs/getMy?user=me
GET http://example.com/jobs/get?query=...
GET http://example.com/jobs/123
GET http://example.com/jobs/123/update?name=t2...
GET http://example.com/jobs/123/instances/start
GET http://example.com/jobs/123/instances
![Page 28: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/28.jpg)
REST Level 2
May 19, 2017
HTTP Verbs Represent Actions
• More complete and structured APIs
Common Verbs
• GET – Read (Nullipotent)
• PUT – Update (Idempotent)
• POST - Create
• DELETE – Remove (Idempotent)
![Page 29: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/29.jpg)
REST Level 2
May 19, 2017
Standard HTTP Response Codes
• Standard results of actions
Success Client Error Server Error
200 OK 400 Bad Request 500 Internal Server Error
201 Created 401 Unauthorized (authentication failure)
204 No Content 403 Forbidden (not allowed access)
404 Not Found
![Page 30: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/30.jpg)
HTTP Verbs for Actions
May 19, 2017
GET http://example.com/jobs/create?name=t&user=me
GET http://example.com/jobs/get?name=test
GET http://example.com/jobs/getMy?user=me
GET http://example.com/jobs/get?query=...
GET http://example.com/jobs/123
GET http://example.com/jobs/123/update?name=t2...
GET http://example.com/jobs/123/instances/start
GET http://example.com/jobs/123/instances
POST http://example.com/jobs
-d '{"name":"test", "user": "me", …}'
GET http://example.com/jobs?name=test
GET http://example.com/jobs?user=me
GET http://example.com/jobs?query=...
GET http://example.com/jobs/123
PUT http://example.com/jobs/123
-d '{"name":"job" …}'
POST http://example.com/jobs/123/instances
GET http://example.com/jobs/123/instances
![Page 31: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/31.jpg)
HTTP Verbs for Actions
May 19, 2017
POST http://example.com/jobs
-d '{"name":"test", "user": "me", …}'
HTTP/1.1 201 Created
[other headers]
{ "id": 123
}
POST http://example.com/jobs/123/instances
HTTP/1.1 403 Forbidden
[other headers]
{ "errorCode" : 10,
"moreInfo" : "no permission to run this job"
}
![Page 32: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/32.jpg)
REST Level 3
May 19, 2017
REST API Documentation and API Discoverability
• Hypertext As The Engine Of Application State (HATEOAS)
— Adds links to response that indicate useful actions
• Open API
— Provides language-agnostic way to describe REST API
— Lots of tooling for automation
![Page 33: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/33.jpg)
Open API
May 19, 2017
![Page 34: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/34.jpg)
Open API
May 19, 2017
![Page 35: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/35.jpg)
Evolution of the API
May 19, 2017
public interface Jobsystem {
Job createAJob(JobDetails details);
void submitJob(Job j);
List<Job> getJobs(String namePattern);
List<Job> getMyJobs(String user);
List<Job> getJobsOther(String query);
Job getJob(int id);
void updateJob(JobDetails details);
}
![Page 36: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/36.jpg)
Evolution of the API
May 19, 2017
![Page 37: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/37.jpg)
Conclusion
May 19, 2017
• Modern day best practices
• Services architectures
• REST APIs
• Resource Oriented Design
• Self-documenting code
• Next steps
• Evolving APIs
• Complex operations
• Error handling, Standard response types
![Page 38: New Principles of REST API Design · 2018. 4. 13. · Our Application May 19, 2017 Application Job Job Job Job Host](https://reader036.fdocuments.in/reader036/viewer/2022071215/6045557c1ab9aa1d67725d01/html5/thumbnails/38.jpg)
Additional Resources
May 19, 2017
http://swagger.io/
https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
https://martinfowler.com/articles/richardsonMaturityModel.html
Published API Guides:https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf
https://github.com/paypal/api-standards/blob/master/api-style-guide.md
https://cloud.google.com/apis/design/
Thank you!