A presentation at DATEV Coding Festival by Daniel Kocot
API Experience – Good design for better and successful APIs that engage with your customers Daniel Kocot, Senior Solution Architect / Head of API Experience & Operations
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/
Customers?
Good Design?
Time Travel
1970s
Dieter Rams
10 Principles of Good Design
Good design is constantly evolving
Time Travel
1995
Jakob Nielsen and Rolf Molich
10 Usability Heuristics for User Interface Design
Time Travel
2017
Ronnie Mitra
7 Usability Heuristics for API Design
#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?
#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?
#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?
#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?
#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?
#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?
#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?
Process
API Management
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
API as a (Digital) Product
Focus on API Experience / Design
User Experience
Design Sprint
Personas & Use Cases
Personas Who is going to use the API?
Introduction of characters
Security discussion in reference to a Persona Building an Authentication / Authorization Flow Technical user Functional user
Use Cases Describing why the API is needed and what systems are involved.
BUT…
You are not the consumer!
API by use case first
API Styles Tunnel Resource Query Event-Based
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
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.
Hypermedia as the Engine of Application State (HATEAOS)
Data Model
Data first
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?
Master Data Management Adopting the idea of a Data Catalog
Data Representation XML JSON Schema JSON for Linking Data (JSON-LD) RDF (Resource Description Framework) CBOR (Concise Binary Object Representation)
API Specification
OpenAPI / AsyncAPI
Specification Version
Focus Rest(ful) APIs
OpenAPI Map
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
OpenAPI Spec Example
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:
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
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”] }
Examples in OpenAPI Descriptions
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”
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
Examples for API Design Patterns Long Running Operations Paging / Filtering Large Payloads
Goal: Establishing a design library
Architecture Discussion
Solutions Architecture Pattern Using patterns which are well established in the industry… But also still evolving But please only adopt them
API-led connectivity
Hybrid integration
Event-Driven architecture
Anti-Corruption Layer
Strangler Pattern
API Endpoint Implementation
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
Generating model classes for clients
API Backend
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
Transformations Use Enterprise Integration Patterns Apache Camel, Spring Integration, Apache Nifi, SaaS Service (e.g. Make), …
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
Testing
Based on the description
Description becomes a contract
Provide a Postman Collection of the API product
Portman
Load testing Smoke Load Stress Soak
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
Q&A
Thank you
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
for free. You
can too.