1. Web Application Interfaces (APIs)
Martin Kruliš
by Martin Kruliš (v1.0)

2. Web Application Architectures
Single Page Applications (SPA)
Web Server
Client
Internet
Browser downloads static content (HTML, JS, …)
Application Frontend
Static Contents
HTML document
and scripts
AJAX, WebSockets, …
API
by Martin Kruliš (v1.0)

3. Application Interface
Web Application Interface
Thick Client
Web Client
Web Server
API
Mobile Client
Another Server
Unified interface for various clients
by Martin Kruliš (v1.0)

4. RPC Remote Procedure Call Server Client foo() foo() Serialized args
wait…
Stub
foo()
Serialized response
by Martin Kruliš (v1.0)

5. RPC in Web Applications
RPC over HTTP(S)
URL identifies script, body identifies function + carries arguments
Regular request (typically POST)
Web Server `
index.php
HTTP
Client
Return value encoded in response body
Application state has to be persisted or the script must be integrated in the server and run all the time
by Martin Kruliš (v1.0)

6. XML RPC XML RPC Generic RPC over HTTP that uses XML for messages
<?xml version="1.0"?>
<methodCall>
<methodName>examples.getTheStuff</methodName>
<params>
<param>
<value><i4>42</i4></value>
</param>
</params>
</methodCall>
32bit (4B) integer
by Martin Kruliš (v1.0)

7. JSON RPC JSON RPC Similar to XML RPC, but uses JSON instead {
"method": "subtract",
"params": [42, 23],
"id": 1 }
"result": 19,
Request
Response
by Martin Kruliš (v1.0)

8. SOAP Simple Object Access Protocol
A successor to XML RPC (also uses XML)
More extensible (e.g., includes security)
Protocol neutral (does not strictly rely on HTTP)
Shifts paradigm from RPC to message passing
<?xml version="1.0"?>
<soap:Envelope xmlns:soap=" xmlns:m="
<soap:Header>
</soap:Header>
<soap:Body>
<m:GetStockPrice>
<m:StockName>BAACEZ</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>
Example taken from
by Martin Kruliš (v1.0)

9. Web Services Web Services
RPC-based services accessible using web technologies (i.e., HTTP)
SOAP
Used for message transfers (RPC calls)
Web service description language (WSDL)
For declaring the interfaces (in XML)
Universal description discovery and integration (UDDI)
Registry and protocol that allows searching for web services
by Martin Kruliš (v1.0)

10. REST API Representational State Transfer (REST)
Server API which offers retrieval and manipulation with application resources in a HTTP-compliant way
Resources are identified by URIs
Operations are performed by HTTP requests
REST formal constraints are
Client-server model
Stateless interface (no client context is cached at server)
Cacheable (response defines whether it can be cached)
Uniform interface
Layered system (proxies, servers may be replicated)
Applications that conform to REST constraints, are typically called “RESTful”.
by Martin Kruliš (v1.0)

11. REST API Representational State Transfer (REST)
HTTP request methods reflect desired operations
GET – retrieve the resource (nullipotent)
POST – append new sub-entity in the resource
PUT – insert/replace the resource (idempotent)
DELETE – remove the resource (idempotent)
Example
API for photo gallery
/gallery – collection of all galleries
/gallery/kittens - photos in gallery with ID=kittens
/gallery/kittens/kitten01 – photo kitten01
by Martin Kruliš (v1.0)

12. REST API REST Example GET POST PUT DELETE /gallery /gallery/kittens
(collection of galleries)
/gallery/kittens
(photos in gallery)
…/kitten01
(single photo)
GET
Get the list of all galleries (JSON)
Get the list of photos in the gallery (JSON)
Get the image (jpeg)
POST
Create a new gallery
Create a new photo in a gallery
Not generally used. Perhaps for adding image metadata…
PUT
Replace list of galleries (atypical)
Replace entire list of photos in gallery
Replace/insert an image (of given ID)
DELETE
Empty the whole application
Remove all photos of a gallery
Remove the given image
by Martin Kruliš (v1.0)

13. REST Frameworks Example
PHP Slim Framework
$app = new \Slim\App();
$app->get('/hello/{name}', function (Request $request, Response $response) {
$name = $request->getAttribute('name');
$response->getBody()->write("Hello, $name");
return $response;
});
$app->run();
The example was taken directly from
by Martin Kruliš (v1.0)

14. REST API DATA Encoding Design
No format prescribed for request/response body
Typically JSON
Parameters may be encoded in URI path or query
Design
Typically influenced by data model
REST API is a tight wrapper for data model operations
Difficult to get right
Many choices
Performance must be considered
by Martin Kruliš (v1.0)

15. Designing (REST) API CRUD Basic functions for persistent storage
Create – POST requests
Read (Retrive) – GET requests
Update – PUT requests
Delete – DELETE requests
Applicable in other situations as well
E.g., in SQL (INSERT, SELECT, UPDATE, DELETE)
Not always optimal performance
Operation aggregation may be required to reduce client-server communication
Typically in case of Read operations
by Martin Kruliš (v1.0)

16. Designing (REST) API Design Approaches Bottom-up Top-down
Coding and testing start early
API is developed as we go based on new features
Top-down
Analysis and interface design must be completed before the coding starts
API-first
Relatively new concept in web apps development
A complete web (REST) API is designed and specified before any other part of the application
by Martin Kruliš (v1.0)

17. Designing (REST) API Collection Endpoints API Versioning E.g. /gallery
Should the endpoint return IDs or nested entities?
Should it contain additional features?
Like search or pagination
API Versioning
Implementation may change often, API not
API version may be part of path
Base URL example /api/v1/
by Martin Kruliš (v1.0)

18. API Modeling API Consistency Modeling
One of the perils of API evolution
Maintaining consistency of clients, server(s), and documentation
Modeling
API is defined by a model
Formally specified
Model is used for
Generating client/server stubs
Generating documentation
Testing, inspections, monitoring, …
by Martin Kruliš (v1.0)

19. API Modeling API Model Specification
In a declarative form (XML, JSON, Yaml…)
The specification can also be generated from the implementation (annotations)
Client Stubs
Server Stubs
Documentation
Testing, …
by Martin Kruliš (v1.0)

20. API Modeling Tools API Modeling Requires Examples
Modeling (declarative) language
Generators
Stubs, documentation, testing scenarios, mockups
Examples
RESTful API Modeling Language (RAML)
Powerful API Design Stack (Apiary)
API Blueprint
OpenAPI Tools (Swagger)
by Martin Kruliš (v1.0)

21. OpenAPI OpenAPI (Swagger API) Originally part of Swagger tools
Separated in 2015, sponsored by many big players
Google, IBM, Microsoft
Language agnostic
Stubs can be generated in many languages
Specification itself is declarative in Yaml or JSON
Current version 3.0
But many language bindings still exists only for version 2.0
by Martin Kruliš (v1.0)

22. OpenAPI OpenAPI (2.x) Specification Crash Course swagger: "2.0" info:
version: 1.0.0
title: API Example
description: An example for NSWI153 course
schemes:
- https
host: webik.ms.mff.cuni.cz
basePath: /exampleapi
OpenAPI version (actually changes to openapi for 3.0)
Basic info
Where the API will be deployed
by Martin Kruliš (v1.0)

23. OpenAPI OpenAPI (2.x) Specification Crash Course paths: /users: get:
summary: Gets all users
responses:
200:
description: A list of user entities
schema:
type: array
items:
properties:
username:
type: string
...
List of API URLs
HTTP method
HTTP response code
Specifying schema of output JSON
Array of objects with defined properties
by Martin Kruliš (v1.0)

24. OpenAPI OpenAPI (2.x) Specification Crash Course /user/{username}:
get:
summary: Gets single user
parameters:
- name: username
in: path
required: true
description: The unique username
type: string
- name: includeDeleted
in: query
description: Return user even if deleted
type: boolean
Parametrized path
Details of path parameter
Additional query parameter
by Martin Kruliš (v1.0)

25. OpenAPI OpenAPI (2.x) Specification Crash Course definitions: User:
required:
- username
properties:
firstName:
type: string
lastName:
username:
...
schema:
$ref: "#/definitions/User"
Reusable definitions of schemas, responses, and parameters
Reference to the local specification
by Martin Kruliš (v1.0)

26. OpenAPI OpenAPI (2.x) Specification Crash Course
Additional constraints, restrictions, defaults, …
username:
type: string
pattern: "[a-z0-9]{8,64}"
minLength: 8
maxLength: 64
Security requirements
Documentation details
Tags (with descriptions)
by Martin Kruliš (v1.0)

27. OpenAPI What is new in 3.0? New version specification keyword
Multiple servers + better way how to define them
Improved security specifications
Components
More complex objects that aggregate schemas, parameters, responses, security schemes, …
Like prototype objects for endpoints
by Martin Kruliš (v1.0)

28. Swagger Tools Swagger Tools Visual editor of OpenAPI specifications
Yaml editor + visualization
Code generator (generate stubs in various languages)
Documentation generator/browser
Interactive UI in HTML5
Testing and validation tools
Mockup and virtualization
Monitoring
by Martin Kruliš (v1.0)

29. Discussion
by Martin Kruliš (v1.0)