REST-API’s and the enterpriseIntroduction for architects and project-managers

By Patrick Savalle, innovation architect NN.

CONTENTS1. API

2. ENTERPRISE

3. REST

PART 1API-BASICS (GENERAL PRINCIPLES)

Application Programmers Interface

Settling an insurance claim

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.

From now on: only REST-API!!!

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.

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?

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?

Part1:~ Api$ API catalogs_

There is an API for everything.

PART 2ENTERPRISE APPLICATION

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!

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!

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?

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!

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!

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.

v

Part2:~ Enterprise$ REST-API’s and functions_

REST-API’s generally map/represent functions, as in a functional decomposition.

• 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

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

• 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

PART 3REST-BASICS

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_fielding_disserta.pdf

Part3:~ Rest$ WHY REST?_

REST ís HTTP. It is the same protocol. Created by the same designer: Roy Fielding.

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

Part3:~ Rest$ PROTOCOL_

HTTP is a plain text conversation between a client and a server. The conversation is

based on actions performed on resourceswhich are addressed by URL’s.

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.

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.

Part1:~ Api$ Maslov’s API_

Good API, bad API, first things first!