rest api’s in a ca plex context -...
TRANSCRIPT
![Page 1: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/1.jpg)
REST API’s in a CA Plex contextAPI Design and Integration into CA Plex landscape
![Page 2: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/2.jpg)
Speaker
Software Architect and Consultant at CM
First AG, Switzerland since 2008 having 30+
years of experience with the CA Plex / 2E
product lines in different roles: developer,
supporter, pre-sales, distributor, project
manager, teacher, mentor, architect and
consultant.
![Page 3: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/3.jpg)
Section 1 - API Design
![Page 4: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/4.jpg)
API Design challenges
Simple to use (spread)
Self explaining / in-band out-of-band
Support major platforms / devices / tooling
Authentication / Authorisation / Encryption
Versioning
Documentation
Appropriate architectural style
Human / Machine
Error reporting / Re-tries
![Page 5: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/5.jpg)
API Design challenges
Long running processes (asynch)
Monitor Events / Webhooks (events)
Data replication / offline clients
Billing services
Server Monitoring, Notification, Stats
Scaleability / Caching / Performance
Transactions, Web transactions
![Page 6: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/6.jpg)
API consumers
Consumers are out of your control
They will do the unexpected
They will not follow the application domain
protocol
Make sure the API server is robust !
![Page 7: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/7.jpg)
Simple to consume
Design from a consumer perspective
Provide API Access Libraries in Java, .Net,
Javascript, if necessary
![Page 8: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/8.jpg)
API Self explaining / explorable
Provide as much information as possible
in-band
Provide links to documentation in-band
(switchable for Dev/Prod)
![Page 9: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/9.jpg)
API documentation
Domain Application Protocol
State transitions
Media types
Link relations
Headers
Status Codes
![Page 10: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/10.jpg)
API Consumer Platform support
Create Libraries for Platforms
Example : AWS S3
![Page 11: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/11.jpg)
API device support
Let consumer decide about the page size
of collections
Use the concept of «Resource
expansion» to minimize data transfer for
mobiles
![Page 12: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/12.jpg)
API Security, Authentication,
Authorisation
Use TLS / HTTPs
Basic Auth (80% case)
Oauth 2.0
OpenId
Difficult to change later on
![Page 13: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/13.jpg)
API Versioning
Use version in the URL (provide a
«latest» version )
Myapi.ex.com/latest/customer/123
Myapi.ex.com/v11/customer/123
Use Version in HTTP Headers
![Page 14: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/14.jpg)
Humans vs. Machine
If possible use one API for both human
and machine web using different
Representations of Resources
Most operations on Business Systems are
the the same for machines and humans
![Page 15: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/15.jpg)
Transaction Client
PUT or POST complete Transaction
Example: Shopping Basket
Send whole order with one request
Example: Payment
Send Payer and Receiver with same request
![Page 16: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/16.jpg)
Transactions Service Boundary
Consumer App
Server
Resource
Transaction Boundary
Domain Model
Database
![Page 17: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/17.jpg)
Web Transactions
Currently no standards
Can be implemented using classic two
phase commit paradigm.
Transaction modeled as a Resource
Transaction Coordinator is a REST
service
![Page 18: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/18.jpg)
Section 2 - API styleRPC / REST
![Page 19: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/19.jpg)
API Styles
Tunneling (SOAP/RPC)
URI style (REST based)
Hypermedia style (RESTful)
Event driven style
![Page 20: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/20.jpg)
RPC/SOAP vs REST
RPC is about functions
REST is about resources
RPC is about many interfaces
REST is about a uniform interface
![Page 21: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/21.jpg)
Design Options triangle
Data types
OperationsService
Instances
![Page 22: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/22.jpg)
Uniform REST interface
Interface Resource
Resource(URI u);
Response options();
Response get();
Response post(Request r);
Response put(Request r);
Response delete();
Response patch(Request r);
![Page 23: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/23.jpg)
RPC remote procedure call (WS*-Stack)
Well established, Tooling available for
major platforms
WS Reliable Messaging
WS Atomic Transactions
WS Security
Hides the remote aspect of operation
(latency)
![Page 24: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/24.jpg)
RPC remote procedure call (WS*-Stack)
Leads to tight coupling to domain in many
cases (tools)
No notion of resource
No hypertext
No caching
![Page 25: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/25.jpg)
RESTful according to Roy Fielding
Level 3 of Richardson’s Maturity Model
qualifies for the attribute RESTful
Many services are called RESTful but do
not adhere to all the constraints
There is a lot of work on standards
(RFC’s) to be done
![Page 26: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/26.jpg)
REST Richardson Maturity Model
![Page 27: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/27.jpg)
REST principles
Unique identification of resources
Standard methods
Representations
Hypermedia
Stateless communication
HTTP is application protocol
![Page 28: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/28.jpg)
Resources
Primary Resources
Business Concepts (Customer, Address,
Order, Account, Idea, Employee)
Sub resources (x «contains» y )
Other Resources
Query, Transaction, Concepts
![Page 29: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/29.jpg)
Representations of Resources
Resources may have many
representations
UI client might get HTML representation
Machine might get XML or JSON
![Page 30: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/30.jpg)
Resources Impedance mismatch
Not every Entity is a resource in the API
Representation of a resource may have
data from many Entities (aggregation)
Representations may contain only a
subset of the attributes of an entity
(projection)
![Page 31: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/31.jpg)
URI’s for resources
Resource Collections
www.ex.com/customers
www.ex.com/customers/12345/orders
Resources
www.ex.com/customers/12345
www.ex.com/customers/12345/orders/89
![Page 32: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/32.jpg)
URI naming rules
Use nouns not verbs
Use plural
www.api.ex.com/customers/1234/orders
Use singular only for singletons
www.api.ex.com/configuration
![Page 33: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/33.jpg)
URI templates
www.api.ex.com/customers/Id/orders
www.api.ex.com/customers/Id/orders/Id
Instruction on how to build an URI
Should not be necessary if HATEOAS is
implemented
![Page 34: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/34.jpg)
Query parameters in URI’s
https://airline.server.test/ticketing_api/flig
ht_id/passenger_id?option=vegetarian&
option=wheelchair
URL Limit 8092 bytes
![Page 35: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/35.jpg)
Collections / Queries
Use Query Parameters if simple
Use concept of Query as Resource
first POST to create a query
(/products/queries)
then you GET the query (/products/queries/1)
Never use HTTP body in GET
![Page 36: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/36.jpg)
Collections Pages / Pagination
Provide a page-size parameter
Provide the total page count in the
response
Use links for navigation (first, prev, next)
Api.ex.com/customers/pages/3
![Page 37: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/37.jpg)
Representations – Media Types
text/HTML
application/json
application/xml
Your own type: application/vnd.xxxx+json
Links to IANA MIME types
http://www.iana.org/assignments/media-
types/media-types.xhtml
![Page 38: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/38.jpg)
Media types contd.
ATOM ASF syndication format
ATOM PUB publishing protocol
ODATA
Collection+JSON
HAL Hypermedia Application Language
SIREN
RDF Resource description framework
![Page 39: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/39.jpg)
Selecting Media type
Depends on the requirements
Choose formats based on JSON or XML
Plan for Hypermedia controls
Type should allow for a link to a Profile
Choose formats that have some
pervasiveness, tool support etc.
![Page 40: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/40.jpg)
HTTP Verbs
GET
PUT
POST
DELETE
PATCH
OPTIONS
HEAD
TRACE
![Page 41: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/41.jpg)
HTTP verbs – safe methods
GET, HEAD, OPTIONS
No changes on the server
![Page 42: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/42.jpg)
HTTP verbs - Idempotence
Idem = same /potence = power
operation that will produce the same
results if executed once or multiple times
GET, HEAD, OPTIONS, PUT, DELETE
must have idempotent results
POST is not idempotent
![Page 43: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/43.jpg)
Overriding HTTP Method
Some proxies support
only POST and GET methods. To support
a RESTful API with these limitations, the
API needs a way to override the HTTP
method.
Use the custom HTTP Header X-HTTP-
Method-Override to override the POST
Method.
![Page 44: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/44.jpg)
Error handling
Do not just send 500 with a stacktrace
Provide meaningful payload
"errors": ["userMessage": "Sorry, the requested resource does not exist","internalMessage": "No customer found in the database","code": 12349,"more info": "http://smx.cmfirstgroup.com/test/api/v1/errors/12349"
]
![Page 45: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/45.jpg)
HTTP status codes
Organized in groups
1xx Informational
2xx Successful
3xx Redirection
4xx Client Error
5xx Server Error
![Page 46: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/46.jpg)
HTTP Headers
Authorization: Bearer 939399399399393
X-HTTP-Method-Override: DELETE
Accept: audio/*;
Location: http://api.ex.com/customer/123
X-Callback: <http://ex.com/callback>;
method="post"
See: RFC 2616
![Page 47: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/47.jpg)
REST API Stateless server
There is no concept of a session in REST
State must be kept on the client
All information needed to perform a request on the server must be passedalong with the request (Headers, representation)
Resource Status (ordered, shipped etc) iskept on the server
![Page 48: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/48.jpg)
Resource caching
The advantage of adding cache
constraints is that they have the potential
to partially or completely eliminate some
interactions, improving efficiency,
scalability, and user-perceived
performance by reducing the average
latency of a series of interactions.
Roy Fielding
![Page 49: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/49.jpg)
Caching
improve speed, because we want to deliver fast content to our consumer
fault tolerance, because we want our service to deliver content also when it encounters internal failures
scalability, because the WWW scales to bilionsof consumers through hypermedia documents and we just want to do the same thing
reduce server load, because we don’t want our servers to compute without the need of it
![Page 50: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/50.jpg)
Cache types
Local Cache
Proxy Cache
Reverse Proxy
Webserver
![Page 51: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/51.jpg)
Cache Strategies
Expiration Model
Max-Age / Expires Header
Validation Model
Conditional GET: If-Modified-Since
Conditional GET: If-None-Match: ETAG
Model depends on business requirements
![Page 52: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/52.jpg)
Invalidating Cache
PUT,POST,DELETE requests will
invalidate the caches that are under your
control.
Remember you cannot control
intermediate caches in request path
DB changes not driven by the API will
probably need to invalidate cache entries
![Page 53: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/53.jpg)
HATEOAS
Hypermedia as the Engine of Application
State
Provide Links and Verbs for state
transitions
![Page 54: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/54.jpg)
HATEOAS
HTTP as Application Protocol
Application domain protocol
Describe possible next actions on resources
using links.
Link relation
URI
HTTP verb to use
Expected Media type
![Page 55: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/55.jpg)
HATEOAS single entry point
GET ordermgr.ex.com
"links":
"all" : "http://ordermgr.ex.com/orders",
"processing" : "http://ordermgr.ex.com/orders?state=processing",
"shipped" : "http://ordermgr.ex.com/orders?state=shipped",
"cancellations: "http://ordermgr.ex.com/cancellations",
"reports" : "http://ordermgr.ex.com/reports"
![Page 56: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/56.jpg)
HATEOAS single entry point
GET ordermgr.ex.com
"links":
"all" : "http://ordermgr.ex.com/orders",
"processing" : "http://ordermgr.ex.com/orders?state=processing",
"shipped" : "http://shipmentmgr.ex.com/orders",
"cancellations: "http://ordermgr.ex.com/cancellations",
"reports" : "http://ordermgr.ex.com/reports"
![Page 57: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/57.jpg)
HATEOAS Benefits
Decoupling of client and server
Changes to resource distribution are
simple (client just follows URI’s)
Server controllable application flow
![Page 58: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/58.jpg)
Hypertext Request Handler
Hypertext Response
Data representationPossible next
operations as links
![Page 59: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/59.jpg)
IANA Link relation values
Self
Next-archive
Prev-archive
First
Last
Payment
http://www.iana.org/assignments/link-relations/link-relations.xhtml
![Page 60: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/60.jpg)
Securing REST
TLS / HTTPs
Do not clutter URI’s with auth information
Use HTTP Headers
![Page 61: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/61.jpg)
Securing REST
Basic HTTP (only over TLS) 80 % case
Oauth 2.0
OpenId
![Page 62: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/62.jpg)
Section 3 - CA Plex and RESTful API’s
![Page 63: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/63.jpg)
RESTful API and CA Plex
No support for RESTful API generator
Should we generate ? Probably not.
CA Gateway and ASO to make use of
existing or new SOAP WCF services for
CRUD is an option
Third party solutions / no announcments
yet
![Page 64: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/64.jpg)
CA Plex Restful API – Resources vs.
Entities
Impedance mismatch
Not every Entity is a resource in the API
Representation of a resource may have
data from many Entities (aggregation)
Representations may contain only a
subset of the attributes of an entity
(projection)
![Page 65: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/65.jpg)
CA Plex Restful API – Links vs. DB
Relations
We should not expose implementation
details
Some Relations will be modeled as links
others will be modeled as sub-resources
or embedded resources in the API
![Page 66: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/66.jpg)
CA Plex – Restful API
Plex architecture based on RPC style
Major effort needed to support REST style
New Plex Object Types (Resource,
Representation).
Exchange dynamic Messages/Documents
instead of fixed function parameters,
HTTP support for Plex Runtime
![Page 67: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/67.jpg)
CA Plex – third party web solutions
Websydian Transact XML
CM Webclient
Plex XML
All of these can adopt REST style.
![Page 68: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/68.jpg)
WCF SOAP API and CA Plex
Create function layer for WCF Services Do not call domain functions directly
Use separate fields on parameterinterfaces for service functions, cast fromdomain fields
WCF SOAP method generation based on Plex Function input/output parms
MOV’s and arrays still fixed size.
![Page 69: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/69.jpg)
RESTful API and CA Plex
Web Server /
Load Balancer/
Cache /Gateway
App Server / Business Logic
DB
REST API using
Framework (.NET, Java)
Plexgenerated
Code
Logic
![Page 70: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/70.jpg)
Write API Services in Java/.Net
.NET WCF Restful Services
Java JAX-RS
Use PlexRuntime to call domain functions
Direct Object to XML or JSON mapping
should be avoided
Resource Handlers, State Machines
Decouple API model and Domain model
![Page 71: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/71.jpg)
CA Plex and App Services Orchestrator
CA API Gateway
App Server / Business Logic
DBPlex
generatedCode
IIS WCF
Plexgenerated Code
ASO generatedcodefromWSDL
CA PlexCA ASO
![Page 72: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/72.jpg)
Application Logic
Logic should be on the server
CRUD only API will lead to «fat clients»
Validation / code duplication
Status Transitions
![Page 73: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/73.jpg)
Datamodel supporting REST
Use GUIDS on Tables
Add a mapping table to the picture
GUID
Tablename
Key Values
![Page 74: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/74.jpg)
Key mapping table
![Page 75: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/75.jpg)
URI composition from ent and keys
Mandate, Customer, Order, Orderline,
Shipmentline
Api.ex.com/mandates/key/customers/ke
y/orders/key/orderlines/key/shipmentli
nes/key
Api.ex.com/shipmentlines/key
![Page 76: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/76.jpg)
Questions ?
![Page 77: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/77.jpg)
Recommended REST reads
RESTful Web API (Leonard Richardson,
Mike Amundsen, Sam Ruby) ENG
REST in Practice (Jim Webber,Savas
Parastatidis,Ian Robinson) ENG
REST und HTTP (Stefan Tilkov, Martin
eigenbrodt, Silvia Schreier) GER
![Page 78: REST API’s in a CA Plex context - plex2e.complex2e.com/.../2015/06/Lorenz_Adler-REST_APIs_in_a_CA_Plex_conte… · REST API’s in a CA Plex context API Design and Integration into](https://reader031.vdocument.in/reader031/viewer/2022012401/5a7436747f8b9a0d558ba1f6/html5/thumbnails/78.jpg)
Thank you [email protected]