Flickr/BenNuttall
flickr/FraserMummery
Example-driven Web API
Specification Discovery
Hamza Ed-douibi, Javier L. Cánovas Izquierdo, Jordi Cabot

Motivation
flickr/airpix

API Economy

API Economy

API Economy

API Economy

API Economy

API Economy

…consortium of forward-looking industry
experts who recognize the immense value
of standardizing on how REST APIs are
described…
…is focused on creating, evolving and
promoting a vendor neutral description
format…
https://www.openapis.org

OpenAPI Example
http://petstore.swagger.io/v2/pet/123GET
"swagger":"2.0",
"host":"petstore.swagger.io",
"basePath":"/v2",
Metadata
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"license": {
"name": "MIT"
}
},
"host": "petstore.swagger.io",
"basePath": "/v1",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/pets": {
"get": {
"summary": "List all pets",
"operationId": "listPets",
"tags": [
"pets"
],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "How many items to return at one time (max 100)",
"required": false,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "An paged array of pets",
"headers": {
"x-next": {
"type": "string",
"description": "A link to the next page of responses"
}
},
"schema": {
"$ref": "#/definitions/Pets"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
},
OpenAPI document

OpenAPI Example
http://petstore.swagger.io/v2/pet/123GET
"swagger":"2.0",
"host":"petstore.swagger.io",
"basePath":"/v2",
Metadata
"paths":{
"/pet/{petId}":{
"get":{
"parameters":[
{ "name":"petId",
"in":"path",...
}
],
"responses":{
"200":...,
},...
},...
},
Operations
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"license": {
"name": "MIT"
}
},
"host": "petstore.swagger.io",
"basePath": "/v1",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/pets": {
"get": {
"summary": "List all pets",
"operationId": "listPets",
"tags": [
"pets"
],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "How many items to return at one time (max 100)",
"required": false,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "An paged array of pets",
"headers": {
"x-next": {
"type": "string",
"description": "A link to the next page of responses"
}
},
"schema": {
"$ref": "#/definitions/Pets"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
},
OpenAPI document

OpenAPI Example
http://petstore.swagger.io/v2/pet/123GET
"swagger":"2.0",
"host":"petstore.swagger.io",
"basePath":"/v2",
Metadata
"paths":{
"/pet/{petId}":{
"get":{
"parameters":[
{ "name":"petId",
"in":"path",...
}
],
"responses":{
"200":...,
},...
},...
},
Operations
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"license": {
"name": "MIT"
}
},
"host": "petstore.swagger.io",
"basePath": "/v1",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/pets": {
"get": {
"summary": "List all pets",
"operationId": "listPets",
"tags": [
"pets"
],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "How many items to return at one time (max 100)",
"required": false,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "An paged array of pets",
"headers": {
"x-next": {
"type": "string",
"description": "A link to the next page of responses"
}
},
"schema": {
"$ref": "#/definitions/Pets"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
},
OpenAPI document
"definitions":{
"Pet":{
"type":"object",
"properties":{
"id":...,
"category":...,
"name“:...,
...
} }
Schema

OpenAPI Example
http://petstore.swagger.io/v2/pet/123GET
"swagger":"2.0",
"host":"petstore.swagger.io",
"basePath":"/v2",
Metadata
"paths":{
"/pet/{petId}":{
"get":{
"parameters":[
{ "name":"petId",
"in":"path",...
}
],
"responses":{
"200":...,
},...
},...
},
Operations
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"license": {
"name": "MIT"
}
},
"host": "petstore.swagger.io",
"basePath": "/v1",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/pets": {
"get": {
"summary": "List all pets",
"operationId": "listPets",
"tags": [
"pets"
],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "How many items to return at one time (max 100)",
"required": false,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "An paged array of pets",
"headers": {
"x-next": {
"type": "string",
"description": "A link to the next page of responses"
}
},
"schema": {
"$ref": "#/definitions/Pets"
}
},
"default": {
"description": "unexpected error",
"schema": {
"$ref": "#/definitions/Error"
}
}
}
},
OpenAPI document
"definitions":{
"Pet":{
"type":"object",
"properties":{
"id":...,
"category":...,
"name“:...,
...
} }
Schema

Advantages
Publication & promotion

Advantages
Publication & promotion Querying

Our approach
flickr/Pascal

Approach

Approach

Approach

Approach

Approach

General view of the approach

Example provision
{
"request": {
"method" : "POST" ,
"url" : "http://petstore... ",
"body" : { ... }
},
"response" : {
"status" : 200,
"body" : { ... }
}
}
{
"request": {
"method" : "GET" ,
"url" : "http://petstore... ",
"body" : { ... }
},
"response" : {
"status" : 200,
"body" : { ... }
}
}
{
"request": {
"method" : "GET" ,
"url" : "http://petstore... ",
"body" : { ... }
},
"response" : {
"status" : 200,
"body" : { ... }
}
}

APIDiscoverer

APIDiscoverer

The OpenAPI Metamodel

APIDiscoverer

Discovery & Enrichment
Source Target
host
basepath
protocol
API
relativePath Path
httpMethod
request-body
response-body
Operation
query
relative-Path
request-Body
Parameter
response-Code Response
request-body
response-body Schema
Behavioral Discoverer
http://petstore.swagger.io/v2/pet/123GET

Discovery & Enrichment
Source Target
host
basepath
protocol
API
relativePath Path
httpMethod
request-body
response-body
Operation
query
relative-Path
request-Body
Parameter
response-Code Response
request-body
response-body Schema
Behavioral Discoverer
http://petstore.swagger.io/v2/pet/123GET
{
"id": 123,
"category": {
"id": 1,
"name": "dogs"
},
"name": "doggie",
"photoUrls": [
"http://exampleTcom"
],
"tags": [
{
"id": 1,
"name": "black"
}
],
"status": "available"
}
Response

Discovery & Enrichment
Source Target
host
basepath
protocol
API
relativePath Path
httpMethod
request-body
response-body
Operation
query
relative-Path
request-Body
Parameter
response-Code Response
request-body
response-body Schema
Behavioral Discoverer
http://petstore.swagger.io/v2/pet/123GET

Structural Discoverer
JSONDiscoverer
Source Target
host
basepath
protocol
API
relativePath Path
httpMethod
request-body
response-body
Operation
query
relative-Path
request-Body
Parameter
response-Code Response
request-body
response-body Schema
Behavioral Discoverer
{
"id": 123,
"category": {
"id": 1,
"name": "dogs"
},
"name": "doggie",
"photoUrls": [
"http://exampleTcom"
],
"tags": [
{
"id": 1,
"name": "black"
}
],
"status": "available"
}
Response
Discovery & Enrichment

Discovery & Enrichment
http://petstore.swagger.io/v2/pet/123GET

APIDiscoverer
Example 1

APIDiscoverer
Example 1
Example 2
Example 3
Example n

Generator
{ "swagger":"2.0",
"info":{ },
"host":"petstore.swagger.io","basePath":"/v2",
"tags":[ "pet" ],"Schemes":[ "http" ],
"paths":{
"/pet/{petId}":{
"get":{
"produces":["application/json"],
"parameters":[{"name":"petId","in":"path","type":"integer"}],
"responses":{
"200":{
"description":"OK",
"schema":{"$ref":"#/definitions/Pet"
}}}}
}},
"definitions":{
"Pet":{
"type":"object",
"properties":{
"id":{"type":"integer"},
"category":{"$ref":"#/definitions/Category"},
"name":{"type":"string"},
"photoUrls":{"type":"array","items":{"type":"string"}},
"tags":{"type":"array","items":{"$ref":"#/definitions/Tag"}},
"Status":{"type":"string"}},
}}}

flickr/CodeRo

Tool Support
APIDiscoverer https://github.com/SOM-Research/APIDiscoverer

HAPI
HAPI (Home of APIs) https://github.com/SOM-Research/hapi
APIDiscoverer
Query

flickr/derekBruff

Conclusion and Further Work
• Application of model-driven techniques for API discovery
• Provided as Open Source tool
• Help developers to integrate APIs
What we have shown
What we plan to do
Extension of HAPI
Automatic call
generation
OpenAPI Extensions
• Quality of Service
• Business Plans
• Security
• Semantics

Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution 4.0 International license.
Thanks!
HAPI (Home of APIs)
https://github.com/SOM-Research/hapi
APIDiscoverer
https://github.com/SOM-Research/APIDiscoverer
Javier L. Cánovas Izquierdo
jcanovasi@uoc.edu
@jlcanovas
Hamza Ed-douibi
hed-douibi@uoc.edu
@mazamiz
Jordi Cabot
jordi.cabot@icrea.cat
@softmodeling