API Design

Elroy Webster D’Silva

T RDA SSI RSE-IN

Restricted © Siemens 20XX siemens.tld/keyword

Table of contents

• Introduction
• Why is API design important?
• Designing a REST API
• Hands-on exercise
• Guidelines for developing maintainable APIs

Restricted © Siemens 2021

Page 2 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
What is an API?

“Application Programming Interface”

“a computing interface that defines interactions between multiple software intermediaries”

“defines the kinds of calls or requests that can be made, how to make them, the data formats that should
be used, the conventions to follow, etc.”

Restricted © Siemens 2021

Page 3 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
More about APIs

APIs are used in several contexts.

• Libraries and frameworks

• Operating systems
• Remote APIs
• Web APIs

Restricted © Siemens 2021

Page 4 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Why is API design important?

APIs are an important communication interface in modern web-applications and web-services.

The design of an API has significant impact on its usage.

• An API is a contract between two communicating parties

• Hide the information that need not be revealed
• Focus on the user of the API
• Know the difference between public and private APIs

Remember!
Difficult to use, inconsistent and buggy APIs can lead to major
dissatisfaction in users and eventually lead to loss of business.

Restricted © Siemens 2021

Page 5 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
What is a RESTful API?

REST – REpresentational State Transfer

Guiding principles of REST:

• Client-server
➢ Separation of concerns - Client and server applications should be able to evolve independently.
• Stateless
➢ Each request is independent, and no context is stored on the server.
• Cacheable
➢ Labeling response data as cacheable or non-cacheable.
• Uniform Interface
➢ REST is defined by four interface constraints: identification of resources; manipulation of resources through
representations; self-descriptive messages; and, hypermedia as the engine of application state.
• Layered system
➢ The layered system style allows an architecture to be composed of hierarchical layers by constraining component
behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.

An API that follows the guiding principles of REST is a RESTful API.

Restricted © Siemens 2021
Page 6 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
REST

At its core, REST consists of:

• Resources - Sources of information referenced by a global identifier such as a URI

• Representations of resources - Documents containing that information

• Components that communicate with one another - Clients and servers

• A standardized interface - An interface that identifies resources, allows for the manipulation of
resources through representations, includes self-descriptive messages that describes how to process
requests and response, and dynamically identified hypermedia.

Restricted © Siemens 2021

Page 7 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
HTTP methods in REST

GET: Requests a resource representation. Should be cacheable.

POST: Creates a new resource. Should return the URI of the created resource.

PUT: Updates or replaces an existing resource.

PATCH: Modifies an existing resource. Only needs to contain changes, not the whole resource.

DELETE: Deletes a resource.

OPTIONS: Requests available communication methods.

HEAD: Requests resource metadata without retrieving the full resource representation.

Restricted © Siemens 2021

Page 8 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
REST API Example

Siemens Health & Travel Declaration App

• Users of the app can declare their daily health status by

answering a questionnaire.
• The system records the declaration and provides a risk
assessment status

The APIs required by the web/mobile app depend on the

requirements stated above.

POST /declarations – Creates and saves a new declaration

GET /assessments – Retrieves the latest risk assessment status

Restricted © Siemens 2021

Page 9 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
General guidelines while developing an API

API Specification
Provide a standard, clean, well documented, and easy to use API specification.

API Security
Only authorized users with secure credentials should be able to access the API.

Audit logging
To understand how the API is used or abused by its user, it is necessary to log the critical information
related to API usages.

Performance
A poorly performing API will not be used by its consumers and thus will cause a loss to the business.

Restricted © Siemens 2021

Page 10 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
How to design a REST API

Steps in designing REST services:

1. Identify Object Model

2. Create Model URIs
3. Determine Representations
4. Assign HTTP Methods
5. Identify Error Codes
6. Document the API

Restricted © Siemens 2021

Page 11 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Designing a REST API

Identify Object Model

Identify the objects which will be presented as ‘resources.’

In our REST example, we can identify the following resources:

• Declaration
• Questionnaire
• Assessment

Restricted © Siemens 2021

Page 12 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Designing a REST API

Create Model URIs

Identify the resource URIs

Remember:
• Focus on the relationship between resources and sub-resources
• URIs should be nouns only. They do not contain any verb or operation.

For our REST example, we have the following URIs:

• /declarations
• /declarations/{id}
• /declarations/{id}/questionnaire
• /assessments
• /assessments/{id}

Restricted © Siemens 2021

Page 13 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Designing a REST API

Determine Representations

• Choose the format – XML, JSON or both.

• Identify the level of detail to be provided in
collections vs. single resource.
• Collection should only contain minimal
information
• Single resource should include complete
information.

Restricted © Siemens 2021

Page 14 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Designing a REST API

Assign HTTP Methods

• Decide the possible operations in the application and map these

operations on resource URIs.

Examples: POST – Create

• Creates and saves a new declaration PUT – Update
• → HTTP POST /declarations PATCH – Partial update
• Retrieves the latest risk assessment status GET – Retrieve
• → HTTP GET /assessments DELETE – Remove
• Retrieve a questionnaire response of a particular declaration
• → HTTP GET /declarations/{id}/questionnaire

Restricted © Siemens 2021

Page 15 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Designing a REST API

Identify Error Codes

• Identify all possible errors that an API may need to return.

• Each error code shall be associated with a corresponding HTTP status code. A few examples are shown
below.

HTTP Status code Used when

200 - OK Indicate success
202 - Accepted Indicate that the request was accepted and is being processed
400 – Bad Request Indicate that the input request contained erroneous or incomplete data
500 – Internal Server Error Indicate that there was an error in processing the request

Restricted © Siemens 2021

Page 16 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Designing a REST API

Document the API

• Use tools like Swagger to review and

communicate the API.

Restricted © Siemens 2021

Page 17 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
REST APIs example

Let’s create and test the APIs!

• Create the POST /declarations API.

• Create the GET /assessments API.

Restricted © Siemens 2021

Page 18 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Developing maintainable APIs

Make sure you follow API development guidelines!

• Humans should be able to easily read and construct APIs.

• Choose domain specific names for resources.
• Ideally URLs should not be too long; Keep it less than 2000 characters.
• Use standard request/response headers like Authorization, Accept, Content-Type, etc.
• Prefer JSON as response format since it is lightweight and easy to use with Javascript clients.
• Provide pagination for collections.
• Ensure that each element in a collection has a key/id.
• Follow standard format for serialization of date and time objects.
• Return standard error codes with additional information where necessary.
• For sub-resources, use path parameters. For filtering, use query parameters.

Restricted © Siemens 2021

Page 19 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Developing maintainable APIs

Best practices for naming

• Use plural nouns to address resources, e.g. /playlists for a collection of playlists. For resources that act
like functions, use verbs (e.g. /playlists/:playlistId/play).
• Do not use file extensions in resource names. Instead of using file extensions in resource names (e.g.
/users.json), the Content-Type header should be supported to retrieve resource representations in
different formats.
• Do not use HTTP operation names in resource names, e.g. prefer /pets over /get-pets.

Restricted © Siemens 2021

Page 20 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Developing maintainable APIs

Versioning

• APIs must support explicit versioning.

• Clients should be able to count on services to be stable over time.
• At the same time, it is critical that services add more features and make changes.
• Increment the version number in response to any breaking change.
• Removing or renaming APIs or API parameters
• Changes in behavior of existing APIs
• Changes in error codes

Restricted © Siemens 2021

Page 21 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Developing maintainable APIs

Long running operations

• The state of the request should be always discoverable and testable.

• Clients may issue a GET on some resource to determine the state of a long running operation.
• Use status code 202 Accepted to indicate that the request has been accepted and may not have been
completed.
• In order to retrieve the status, the client may choose one of the following options:
• Polling – Query the resource status periodically
• Push notification – The service notifies the client on completion
• Define a retention policy for operation results

Restricted © Siemens 2021

Page 22 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Developing maintainable APIs

Idempotence

• For an operation to be idempotent, clients can make that same call repeatedly while producing the same
result.
• The PUT and DELETE methods are defined to be idempotent.
• POST method is not idempotent.
• The problem with DELETE, which if successful would normally return a 200 (OK) or 204 (No Content), will
often return a 404 (Not Found) on subsequent calls, unless the service is configured to "mark" resources
for deletion without actually deleting them.

Restricted © Siemens 2021

Page 23 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Exercise for participants

Design the REST API for the following use cases.

• A device has the following attributes – id, name, configuration[], status(ON, OFF)
• A configuration has the following attributes – id, var1, var2, var3

Design and document the following APIs:

• Retrieve a collection of device objects.
• Retrieve a set of configurations assigned to a device.
• Add a new configuration to an existing device
• Modify an existing device configuration
• Delete a configuration from an existing device.
• Turn on a device/Turn off a device

Restricted © Siemens 2021

Page 25 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN
Contact

Elroy Webster D’Silva

Software Architect
T RDA SSI RSE-IN
Electronic city, Bengaluru
India

Phone: +91 9740299025

E-mail:
[email protected]

siemens.com

Restricted © Siemens 2021

Page 26 2021-02-04 Elroy Webster D’Silva / T RDA SSI RSE-IN