REST-API's for architects and managers

1. REST-API’s and
the enterprise
Introduction for architects and project-managers
By Patrick Savalle, innovation architect NN.

2. CONTENTS
1. API
2. ENTERPRISE
3. REST

3. PART 1
API-BASICS (GENERAL PRINCIPLES)

4. Application Programmers Interface

6. Settling an insurance claim

7. Part1:~ Api$ Evolution_
• Compile time libraries for a specific language
• Language independent, platform specific, run-time local libraries (e.g. DLL’s
on Win)
• Platform independent, language independent, run-time, non-local libraries
• HTTP-REST, everything on the internet can connect, language independent,
run-time, internet libraries
Same name for many things.

8. From now on: only REST-API!!!

9. Part1:~ Api$ What are REST-API’s?_
• Strictly spoken a REST-API is just an interface, a specification: it hides ‘an
implementation’ and standardizes its usage and connectivity
• Pragmatically spoken a REST-API is a library (of functionality) connected
over HTTP(S)
• They are the servers in a client-server model
• These libraries can be built in every programming language
• These libraries can contain any type of functionality: financial services, mail-
service, math, AI, sensor/attenuator, etc.
REST-API’s are the building blocks of the IoT.

10. REST-API’s can contain (encapsulate) any type of technology.
• Software programs
• Mechanics
• Biologics
• Mechatronics
• Human operators etc.
• Connections to other API’s or systems
Part1:~ Api$ Implementation_
What is inside? How are they implemented?

11. Everything on the internet can connect to a REST-API:
• Other API’s
• Server applications
• Web applications and web front ends (built with frameworks like AngularJS,
ReactJS, JQuery)
• Terminals
• Mobile app’s, applications etc.
• Machines
Part1:~ Api$ Users_
What is connected? Who are the run-time users?

12. Part1:~ Api$ API catalogs_
There is an API for everything.

13. PART 2
ENTERPRISE APPLICATION

14. Part2:~ Enterprise$ Business perspective_
• The REST-API unlocks new markets and types of customers (machines)
• The REST-API enables new business models
• The right REST-API can transform the enterprise into a IoT platform, the
realm of exponential growth
• It is the universal channel upon which all other channels can be built
What use is a REST-API to the business? It is Product!

15. Part2:~ Enterprise$ Architects perspective_
• Primary enabler of the digital enterprise
• The REST-API is (should be) the primary unit of modularity of the
enterprise, internally as well as to external clients
• REST-API’s are building blocks that are integrated/combined into business
processes with tools like BPM and apps
• REST-API’s promote autonomy of underlying systems. They also separates
UI/process from basic data manipulation
What is a REST-API to the architect? Modularity!

16. Part2:~ Enterprise$ Programmers perspective_
• For the programmer that uses an REST-API, it’s just another code-library.
Most API’s come with a language specific ‘wrapper’ that hides the API itself.
To this programmer it no longer makes a difference whether it is REST or
SOAP, or JSON or XML etc.
• Convenience!
What is an API to the consuming programmer?

17. Part2:~ Enterprise$ Programmers perspective_
• The programmer that creates an API needs a suitable framework. Typically
NOT the same frameworks that are used for traditional web-design.
• API-design is NOT web-design, it’s ‘traditional’ application-design.
• The API-developer does not need visual design or visual UI skills.
• He does need good ‘interface designer’ skills, which means he needs to be
able to switch from his role as an API-creator into that of an API-user.
What is an API to the producing programmer? Deliverable!

18. Part2:~ Enterprise$ Team perspective_
• Ideally teams are formed around API’s, the operation of the API is their
‘deliverable’, not the API itself.
• Ideally (agile) teams are multidisciplinary: BizDevOps  they not only
develop but also run and support the API
• Ideally all teams have an API / interface designer role
• Teams MUST have autonomy in managing their API’s
What is a REST-API’s to the team? Tool!

19. Part2:~ Enterprise$ Technology landscape_
• HTTP. The basic communication protocol of the web and thus the
Enterprise
• CORBA. Distributed objects, synchronous inter-process communication
(legacy, deprecated). ‘The enterprise as one big application’
• MQ. Message Queue. Asynchronous, loosely coupled, event-driven inter-
process communication based on message-broadcasts and message-loops
• ESB. Enterprise Service Bus, client-server model, SOA-architecture,
facilitates REST, SOAP -> ‘the enterprise as one big collection of services’
• BPM and MDM. Bussiness process and master data management. Tools
that integrate services into processes
• Streaming data. Simple queueing service, ‘fast data’, real-time, scalable.
• Gateway. ‘The switch board’. Does filtering, authentication, integration,
scaling etc. mostly used in combination / integrated with an ESB
• Web API. An HTTP library, RPC-like, point-to-point. The server in a client-
server combination
Gluing an enterprise together.

20. v
Part2:~ Enterprise$ REST-API’s and functions_
REST-API’s generally map/represent functions, as in a functional decomposition.

21. • REST-API’s are designed outside-in, based on client perspective (clients
can be internal)
• Ideally REST-API’s are designed before they are implemented and endpoint
tests should be coded before the REST-API is implemented (test-driven
development)
• REST-API implementations are not based on extensive architectures,
patterns or layering, as integration is typically done in clients (BPM tools,
apps, etc.)  REST-API’s are typically very simple internally
• Consider implementing a REST-API as a (set of) microservices
• The goal should be to have only open REST-API’s / every REST-API should
be open
Part2:~ Enterprise$ Implementation_
Some design and implementation guidelines

22. Part2:~ Enterprise$ Connecting_
API-connection guidelines
• API gateway is the central hub (routing, authentication, translation, etc.)
• Ideally all internal clients consume API’s (also the external API’s)
through the API gateway
• Customer API’s are exposed only through the API-gateway
• API management is the publication and administration tool for teams

23. • Internal vs. external / customer facing
• Lifecycle management
• Versioning
• Integration and remixing of API’s
• Access management
• Throttling
• API keys / customer tracking
• Documentation
• Discovery
• Communities
Part2:~ Enterprise$ Api management_
REST-API’s are more than just deliverable

24. PART 3
REST-BASICS

26. REST is HTTP/1.1. It is the native protocol of the web. Advantages are:
• Every tool that can handle HTTP, can handle REST as native ‘content’. For
instance gateways, web-servers and browsers can effectively cache, route,
verify, manipulate REST requests or responses.
• In short the whole web supports REST by nature
• It is simple and elegant
• Less diversity in technology, you already use HTTP
See also the dissertation of Roy Fielding:
• https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf
• http://www.cs.colorado.edu/~kena/classes/7818/f08/lectures/lecture_9_fieldi
ng_disserta.pdf
Part3:~ Rest$ WHY REST?_
REST ís HTTP. It is the same protocol. Created by the same designer: Roy Fielding.

27. Part3:~ Rest$ SOAP vs REST_
• REST is URL-based, SOAP is procedure-based
• REST is not only a protocol, it is also an architectural style (HTTP is the
protocol)
• REST is much simpler, less strict, can use any data format, any
authentication method
• REST is transport-bound (HTTP), SOAP can be used with any transport
protocol (even SMTP for instance, or REST)
• REST is more scalable, more efficient, client-side cacheable, etc.
See also: https://www.quora.com/What-is-the-difference-between-a-SOAP-
API-and-a-REST-API/answers/19883425

28. Part3:~ Rest$ PROTOCOL_
HTTP is a plain text conversation between
a client and a server. The conversation is
based on actions performed on resources
which are addressed by URL’s.

29. Part3:~ Rest$ ENDPOINTS_
The REST protocol is based on ‘endpoints’, which are
operations on resources addressed by URL’s.
Endpoints can be bundled to form an API.

30. ACTION RESOURCE
<verb> https://<host>/<api_version>[/<resource_type>/<instance_id>]
GET https://animal.api/1/lions (returns collection)
GET https://animal.api/1/lions/harry@lion.com (returns single lion)
POST https://animal.api/1/lions (create new element)
PUT https://animal.api/1/lions/harry@lion.com (updates element)
PATCH https://animal.api/1/lions/harry@lion.com (partial update)
DELETE https://animal.api/1/lions (deletes collection)
DELETE https://animal.api/1/lions/harry@lion.com (deletes single element)
GET http://www.example.com/1/customers/33245/orders/8769/lineitems/1
GET https://animal.api/1/lions?start=100&count=50
GET https://animal.api/1/lions?id=100&id=103&id=107 (array)
Part3:~ Rest$ ACTION + RESOURCE_
An endpoint has a very strict URL structure. This is key to
‘REST’. Map your functional application resources onto the WWW
and allow them to be manipulated.

31. Part1:~ Api$ Maslov’s API_
Good API, bad API, first things first!