API Experience

A presentation at DATEV Coding Festival in July 2022 in by Daniel Kocot

Slide 1

API Experience – Good design for better and successful APIs that engage with your customers Daniel Kocot, Senior Solution Architect / Head of API Experience & Operations

Slide 2

Name: Daniel Kocot Role: Senior Solution Architect / Head of API Experience & Operations Email: daniel.kocot@codecentric.de Twitter: @dk_1977 LinkedIn: https://www.linkedin.com/in/danielkocot/

Slide 3

Customers?

Slide 4

Good Design?

Slide 5

Time Travel

Slide 6

1970s

Slide 7

Dieter Rams

Slide 8

10 Principles of Good Design

Slide 9

Good design is constantly evolving

Slide 10

Time Travel

Slide 11

1995

Slide 12

Jakob Nielsen and Rolf Molich

Slide 13

10 Usability Heuristics for User Interface Design

Slide 14

Time Travel

Slide 15

2017

Slide 16

Ronnie Mitra

Slide 17

7 Usability Heuristics for API Design

Slide 18

#1 Visibility of system status Is it difficult to learn when something has gone wrong in the system? Does the interface tell us the result of invocations and requests? Should the system describe any relevant side-effects that may have occurred?

Slide 19

#2 Match between the system and the real world Do the message formats, libraries and message patterns match the user’s world? Is the vocabulary of the API a good match for the user? Does the API act like the APIs that users are used to using?

Slide 20

#3 Consistency and standards Is the API consistent in its signature (e.g. URI format, query controls)? Is the vocabulary of the API consistent? Do words have the same meaning everywhere? Is the documentation and support tooling consistent across all parts of the API? Does the runtime behavior match the documented behavior?

Slide 21

#4 Error prevention Are documented examples incorrect or misleading? Is the API designed in a way that makes it “brittle” — where changes to the interface can easily break the application? Is the design overly complex? Are there opportunities to simplify the cognitive workload of the user?

Slide 22

#5 Flexiblity and efficiency of use How suitable is the interface for the first-time user? Does the API provide controls and shortcuts for more advanced and experienced users? Are defaults used for special controls? Are there opportunities to optimize any repetitive or unnecessary steps?

Slide 23

#6 Help user recognize, diagnose and recover from errors Is error information correct? Is machine readable information provided? Does it describe the error in a way that the human use can understand it? Is enough information provided to correct the error?

Slide 24

#7 Help and documentation Does the documentation address the needs of different learning stages (beginner, intermediate and expert?) How much documentation needs to be read before a call can be made? Are examples provided in the docs? How well does the documentation structure map to the problems that a user will try to solve?

Slide 25

Process

Slide 26

API Management

Slide 27

API first An API is the first (and often only) interface to users of an application An API comes first — before the implementation An API is described (documented) or self-descriptive

Slide 28

API as a (Digital) Product

Slide 29

Focus on API Experience / Design

Slide 30

User Experience

Slide 31

Design Sprint

Slide 32

Slide 33

Personas & Use Cases

Slide 34

Personas Who is going to use the API?

Slide 35

Introduction of characters

Slide 36

Security discussion in reference to a Persona Building an Authentication / Authorization Flow Technical user Functional user

Slide 37

Use Cases Describing why the API is needed and what systems are involved.

Slide 38

BUT…

Slide 39

You are not the consumer!

Slide 40

API by use case first

Slide 41

API Styles Tunnel Resource Query Event-Based

Slide 42

Richardson Maturity Model for Web APIs Level 0: API uses RPC style Level 1: API exposes Resources Level 2: API uses HTTP methods and uses HTTP efficiently Level 3: API uses HATEOAS. The API is self-documenting and flexible

Slide 43

Dissertation by Roy Thomas Fielding (2000) Architectural Styles and the Design of Network-based Software Architectures REST emphasizes scalability of component interactions, generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems. I describe the software engineering principles guiding REST and the interaction constraints chosen to retain those principles, contrasting them to the constraints of other architectural styles. Finally, I describe the lessons learned from applying REST to the design of the Hypertext Transfer Protocol and Uniform Resource Identifier standards, and from their subsequent deployment in Web client and server software.

Slide 44

Hypermedia as the Engine of Application State (HATEAOS)

Slide 45

Data Model

Slide 46

Data first

Slide 47

Internal vs. External data model Does the existent data model support the required use cases? Is a middleware for the aggregations and/or transformations needed?

Slide 48

Master Data Management Adopting the idea of a Data Catalog

Slide 49

Data Representation XML JSON Schema JSON for Linking Data (JSON-LD) RDF (Resource Description Framework) CBOR (Concise Binary Object Representation)

Slide 50

API Specification

Slide 51

OpenAPI / AsyncAPI

Slide 52

Specification Version

Slide 53

Focus Rest(ful) APIs

Slide 54

OpenAPI Map

Slide 55

Principles Rest(ful) HTTP Object oriented interface Rest(ful) HTTP getEmployees() GET /employees updateEmployee(id) PUT /employees/{id} addEmployee() POST /employees deleteEmployee(id) DELETE /employees/{id} getEmployeeRoles(id) GET /employees/{id}/roles

Slide 56

HTTP Methods HTTP Methods / Verbs Safe Idempotent GET X X HEAD X X PUT

X POST

DELETE

X OPTIONS X X PATCH

Slide 57

OpenAPI Spec Example

Slide 58

OpenAPI Description Example openapi: 3.0.3 servers: - url: ‘http://localhost:8080’ info: version: 1.0.0 title: News API contact: name: Daniel Kocot url: ‘http://www.codecentric.de’ email: daniel.kocot@codecentric.de license: name: MIT url: ‘https://www.tldrelgal.com/mit’ description: An API to provide news tags: - name: news paths: /news: get: description: gets latest news operationId: getNews tags: - news responses:

Slide 59

Errorhandling 1xx serves information purposes 2xx is used for successful request 3xx shows redirects 4xx is used for client-side errors 5xx is used for errors

Slide 60

Problem Details for HTTP APIs (RFC7807) HTTP/1.1 403 Forbidden Content-Type: application/problem+json Content-Language: en { “type”: “https://example.com/probs/out-of-credit”, “title”: “You do not have enough credit.”, “detail”: “Your current balance is 30, but that costs 50.”, “instance”: “/account/12345/msgs/abc”, “balance”: 30, “accounts”: [“/account/12345”, “/account/67890”] }

Slide 61

Examples in OpenAPI Descriptions

Slide 62

Media Type Object responses: ‘200’: description: response content: application/vnd.github.v3.object: schema: “$ref”: “#/components/schemas/content-tree” application/json: schema: oneOf: - “$ref”: “#/components/schemas/content-directory” - “$ref”: “#/components/schemas/content-file” - “$ref”: “#/components/schemas/content-symlink” - “$ref”: “#/components/schemas/content-submodule” examples: response-if-content-is-a-file: “$ref”: “#/components/examples/content-file-response-if-content-is-a-file” response-if-content-is-a-directory: “$ref”: “#/components/examples/content-file-response-if-content-is-a-directory” response-if-content-is-a-symlink: “$ref”: “#/components/examples/content-file-response-if-content-is-a-symlink” response-if-content-is-a-submodule: “$ref”: “#/components/examples/content-file-response-if-content-is-a-submodule”

Slide 63

Schema Object Examples components: schemas: ArticleList: title: ArticleList type: array items: $ref: ‘#/components/schemas/Article’ Article: title: Article description: A article is a part of a news. type: object properties: id: type: integer title: type: string example: First Article date: type: string pattern: ‘^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$’ example: “20210525” description: type: string example: A description

Slide 64

Examples for API Design Patterns Long Running Operations Paging / Filtering Large Payloads

Slide 65

Goal: Establishing a design library

Slide 66

Architecture Discussion

Slide 67

Solutions Architecture Pattern Using patterns which are well established in the industry… But also still evolving But please only adopt them

Slide 68

API-led connectivity

Slide 69

Hybrid integration

Slide 70

Event-Driven architecture

Slide 71

Anti-Corruption Layer

Slide 72

Strangler Pattern

Slide 73

API Endpoint Implementation

Slide 74

API Mediation Architectural layer to manage, protect and enrich an API Intercepting API traffic Concept of “outer” APIs No business logic should be handled within this layers

Slide 75

Generating model classes for clients

Slide 76

API Backend

Slide 77

Services for Backend Systems Use a framework the development team is proficient with To create a first representation of the data Transformation is maybe needed

Slide 78

Transformations Use Enterprise Integration Patterns Apache Camel, Spring Integration, Apache Nifi, SaaS Service (e.g. Make), …

Slide 79

Services for Aggregations Use again a framework the development team is proficient with To create aggregated oder composed representation of data from Backend APIs These APIs help to create a better experience for the user

Slide 80

Testing

Slide 81

Based on the description

Slide 82

Description becomes a contract

Slide 83

Provide a Postman Collection of the API product

Slide 84

Portman

Slide 85

Load testing Smoke Load Stress Soak

Slide 86

Wrap Up Posts on codecentric blog: https://blog.codecentric.de/en/author/daniel-kocot/ Posts on my blog: https://danielkocot.github.io Posts on Medium: https://medium.com/@daniel.kocot

Slide 87

Q&A

Slide 88

Thank you

Slide 89

References Photo by Blake Wisz on Unsplash By docsearls - Flickr, CC BY-SA 2.0, https://commons.wikimedia.org/w/index.php? curid=1328081 Photo by Jean-Philippe Delberghe on Unsplash Photo by Kelli McClintock on Unsplash Photo by Faizur Rehman on Unsplash Photo by Erik Mclean on Unsplash Photo by Markus Spiske on Unsplash Photo by John Salvino on Unsplash Photo by Gautam Lakum on Unsplash Photo by Fredy Jacob on Unsplash Photo by Emil Widlund on Unsplash Photo by Dan Dennis on Unsplash