Interoperable APIs

The Italian Government - like other Countries - is standardizing REST APIs to create an uniform developer experience for software provided by its:

20 Regions
8_000 municipalities
20_000 local and central agencies

At the core of this interoperability strategy we have:

API First Approach with OpenAPI v3
HTTPS everywhere
Service Management with standardized throttling and circuit-breaker patterns
Standardized approach to metrics

See Slides

This training

In this training we'll show how to:

model interoperable API
leverage interoperability by reuse

We'll use connexion, a python framework which streamlines API creation.

REST and RPC

The historical API approach was to view any interaction like a function call.

In a network environment this is seen as a Remote Procedure Call. SOAP web services have this approach, where you bind:

a service to an URL
and different functions to invocation methods.

Even today there are a lot of non-SOAP APIs using an RPC approach, including Slack APIs and Google RPC.

The widespread of HTTP as a distributed computation protocol, and the rise of data give birth to REST.

REST, aka REpresentation State Transfer, is not a protocol, but an architectural style which mimics the distributed characteristics of the web.

In REST, everything is a resource:

identified by an Uniform Resource Locator URL;
which is conveyed by a representation. A given resource could be represented as application/json or as application/xml, in different languages (see Content-Language) and differently encoded (see Content-Encoding);
whom state is transferred between an Origin Server and a User Agent (see RFC7230);

There are no "functions" but everything is modeled as a resource. Moreover all the HTTP semantics (RFC7231) applies, including idempotent and non-idempotent methods and caching.

The REST architectural style allows us to leverage the distributed nature of the web and the features of HTTP which are redesigned with REST in mind (see RFC723x and the new http-core Internet-Drafts).

While REST is not a silver bullet, we acknowledged that public services are usually about data and resources making a REST style a good approach in service modeling.

Moreover a semantic approach to URIs simplifies routing and auditing based on http status, method and path.

Other advantages of HTTP APIs

We expect that REST/HTTP APis will:

Enable the creation of new services for citizens, lowering setup and maintenance/operation costs
Simplify communication with non-governmental agencies
Keep current with the IT world ;)

REST without Richardson Maturity Model constraints

Describing APIs

Providing usable digital services requires:

publishing interfaces;
involve stakeholders/users in the service lifecycle.

You must COMMUNICATE:

technical specifications;
service metadata;
documents and references.

Interface Description Language

Digital service description requires an Interface Description Language. That's a machine readable language that can be used to describe the interface. The most famous IDL is WSDL used by SOAP web services.

For REST APIs the standard IDL is OpenAPI v3 aka OAS3.

For example, a web service accepting the following request GET /echo and returning a json object could be described in OAS3 like the following:

...
paths:
  /echo:
    get:
      responses:
        "200":
          application/json: {}
...

This allows to disambiguate the API definitions and usage.

Contract first, Code first

There are two paths for API writing:

code first: where one develops a function on a specific language and then uses some tool to generate the IDL. An example function generating the above IDL could be
```
def echo():
    item = {"hello": "world"}
    status_code = 200
    headers = {'content-type': 'application/json'}

    return item, status_code, headers
```
contract first: one writes down the interface in an IDL, then let the tools generate the code stubs.

Contract first improves standardization

While lazy developers prefers to use code-first, as they could focus on writing the actual code and leave the interface as an underproduct, this approach rarely works in a large ecosystem where

different actors
in a long timeframe
works with different frameworks and enviroments.

A contract-first approach has many advantages:

allows to focus on the actual design of the API, without being entangled by implementation details;
it's independent from which framework or language people uses for its client/server implementation and from how frameworks generate the specs (which may be buggy);

Focusing on the specs allows to create API modeling iterations that enable the API to change fast and involve stakeholders in the modeling and in the API lifecycle.

NB: this doesn't mean iterations don't involve testing that the actual code works ;)

Interoperability requirements

In our API work we identified some basic standardization features required to create a sane ecosystem:

Standardize HTTP APIs for 20k agencies and 60M people
API-first approach to REST APIs
Scheme standardization based on national, European and industry standards (includes dates and log timestamping format)
Availability strategy based on a distributed circuit-breaker and throttling patterns
National API Catalogue