WSO2Con2024 - Simplified Integration: Unveiling the Latest Features in WSO2 L...
Â
There is REST and then there is "REST"
1. There is REST and
then there is “REST”
Radovan SemanÄŤĂk
November 2017
2. Who Am I?
Ing. Radovan SemanÄŤĂk, PhD.
Software Architect at Evolveum
Architect of Evolveum midPoint
Apache Foundation committer
Contributor to ConnId and Apache Directory API
3. What is REST?
Server
JavaScript in browser
Mobile application
Enterprise application
CLI tool
Desktop client
…
Client HTTP
JSON
request
Web application
Enterprise application
“Cloud” application
Whatever as a Service
“Serverless” server
...
JSON
response
4. What is REST?
Server
JavaScript in browser
Mobile application
Enterprise application
CLI tool
Desktop client
…
Client HTTP
JSON
request
JSON
response
Web application
Enterprise application
“Cloud” application
Whatever as a Service
“Serverless” server
...
This is simple, easy to understand … and wrong
5. Who Are You?
I know
everything
about
REST
already
Whatever.
I do not need
to know REST
This may be interesting
6. Back to 1990s ...
â—Ź 1990: WWW invented
• Tim Berners-Lee
â—Ź 1996: HTTP 1.0
â—Ź 1997: HTTP 1.1
â—Ź 2000: Representational State Transfer
• Roy Fielding
â—Ź 2002: WWW Architecture
8. REST (according to Fielding)
â—Ź Architectural style
• Not “architecture”, not “protocol”, not “API”
â—Ź Retro-architecture (HTTP 1.1)
â—Ź Transfer of resource representations
• HTML page is a representation, HTTP is transfer protocol
â—Ź Architectural constraints
• Client-server, Stateless, Cache, Uniform interface, Layered
system, Code on demand
12. Request-response … kind of ...
ServerClient HTTP
URL
resource
representation
Operations (verbs):
â—Ź GET
â—Ź PUT
â—Ź DELETE
â—Ź POST
â—Ź ...
13. REST is not RPC
â—Ź Objects (resources) addressed by URL
â—Ź Fixed operation set (verbs)
• GET, HEAD, PUT, DELETE, POST, OPTIONS, TRACE, CONNECT
â—Ź Stateless
• Sessions are evil
â—Ź Hypertext
• Thou shalt not construct your URLs
14. Theory and Practice
â—Ź Theory: REST is architectural style for
hypertext applications
â—Ź Practice: we really need RCP
â—Ź REST is not good for RPC
… but REST is popular, we want it …
â—Ź Result: RESTful APIs
15. RESTful APIs
â—Ź Not really REST
• Not hypertext
• Mostly resource-based, but still some RPC
â—Ź Not really API
• Application Programming Interface
• Problematic interface definition (Swagger/OpenAPI?)
• Security? Reliability? Transactions?
● Read: “HTTP-based service”
17. Pure REST
â—Ź It is possible to implement pure REST service
… but it is going to be real pain (very likely)
• Careful design and implementation
• Unnecessary complexity
• Too many network round-trips
• Expect poor performance
â—Ź Hypertext is not suitable for everything
18. What do we do?
â—Ź Keep the parts that fit
• Resources, URLs, representations
• GET, DELETE, POST, …
â—Ź Ditch the parts that do not fit
• Hypertext
â—Ź Compromises
• Statelessness, caching, security, consistency, ...
â—Ź Interface definition
• Swagger/OpenAPI
19. Practical “REST”
â—Ź Try to stick to resources and representations
• URL represents object (resource)
â—Ź GET as safe operation
â—Ź Use POST for RPC when needed
• But do not abuse
â—Ź Define the interface
• URL formats and meaning, data types, inputs/outputs, ...
20. Practical case study: midPoint
â—Ź MidPoint: comprehensive identity
management and governance system
• Identity management, provisioning, role-based access control,
audit, workflow, entitlement management, password management,
policy management, segregation of duties, …
â—Ź 100% open source
â—Ź Started in 2011
â—Ź 700k lines of (mostly) Java code
21. (things are a bit
complex in this part)
MidPoint Services
midPoint
Self-service
application
IDE
User
Developer
Custom
client
Enterprise
integration
Mobile
application
22. MidPoint “REST” service
â—Ź Development started in 2013
â—Ź Existing data model and operations
• Object-based: User, Role, Organizational unit, Account, Task,
Security policy, ...
• CRUD … but there are exceptions
● “RESTful” part and RPC part
â—Ź Kept as close to REST ideas as was practical
24. How does object look like?
<user oid="02c15378Âc48bÂ11e7Âb010Â1ff8606bae23">
    <name>jack</name>
    <description>Where's the rum?</description>
    <fullName>Jack Sparrow</fullName>
    <givenName>Jack</givenName>
    <familyName>Sparrow</familyName>
    <emailAddress>jack.sparrow@evolveum.com</emailAddress>
    <locality>Caribbean</locality>
    <activation>
    <administrativeStatus>enabled</administrativeStatus>
    </activation>
</user>
{
    "name" : "jack",
    "fullName" : "Jack Sparrow",
    "givenName" : "Jack",Â
    "familyName" : "Sparrow",
    …
XML
JSON
27. HTTP verbs
â—Ź GET is safe
â—Ź POST used for many things
â—Ź DELETE deletes
â—Ź PUT is not very useful
â—Ź PATCH for modification
• But POST works as well
● Typical “REST” API
28. Error Codes
â—Ź 1xx: Information. Stay tuned.
â—Ź 2xx: Success. All done.
● 3xx: Redirection or “in progress” (we will get to that)
â—Ź 4xx: Client error (e.g. bad request)
â—Ź 5xx: Server error (e.g. bug in server code)
33. Object-related RPC operations
â—Ź Deviation from pure REST
• Should be modeled as resource changes or separate resources
… but that is a pain
â—Ź Error handling
35. Global RPC operations
â—Ź Complex input and output data structures
â—Ź Huge deviation from pure REST
â—Ź It was necessary to keep the interface simple
and efficient
37. Security
â—Ź REST is stateless
• Cookie-based sessions are out
â—Ź HTTP Basic authentication
• Oh, really?
â—Ź OAuth2 / OpenID Connect
• “best” practice for REST APIs
â—Ź JSON Web Tokens (JWT)
• SAML tokens reinvented
38. Interface Definition
â—Ź Swagger / OpenAPI
• WSDL reinvented (CORBA IDL reinvented)
• JSON-oriented
• Still quite limited, but at least something
â—Ź REST purists hate it
• Because this goes directly against hypertext principles
40. Transactions and Consistency
â—Ź Transactions (ACID)
• Forget it
â—Ź Consistency
• Cannot forget it, but it is tricky
• Optimistic locking / MVCC is best bet
• ETag (RFC7232) is a standard mechanism
• But a lot of proprietary mechanisms is used instead
41. Conclusion
â—Ź REST is no good for RPC
… but we are going to use it anyway
â—Ź And it is practical
… with some tweaks and compromises
â—Ź Future?