API Experience - Speaker Deck

Slide 1

Slide 1 text

API-Experience 1

Slide 2

Slide 2 text

codecentric AG Hoher Wall 15 44137 Dortmund Telefon: +49 (0) 151. 10 86 70 74 Daniel Kocot Head of API Experience [email protected] www.codecentric.de Innovative - Trustful - Competent - Pragmatic 2

Slide 3

Slide 3 text

Daily Routine: Searching for data and creating new value for the organisation 3

Slide 4

Slide 4 text

API as a medium of transport 4

Slide 5

Slide 5 text

5 API first When we talk about API-first, it's important that you and your organisation recognise that APIs need to be prioritised so that your teams can achieve connectivity, productivity and quality.

Slide 6

Slide 6 text

Consumer Journey 6 Discovery by the business and the development API Thinking Delivery to a platform of choice Usage

Slide 7

Slide 7 text

Searching for data and not in… Discovery 7

Slide 8

Slide 8 text

Design Thinking with APIs and data 8

Slide 9

Slide 9 text

Slide 10

Slide 10 text

Classical Design Thinking 10 Empathise Define Ideate Prototype Test

Slide 11

Slide 11 text

API Thinking 11 Empathise with stakeholders Data definition API definition API endpoint and backend implementation Test by stakeholders

Slide 12

Slide 12 text

Business & Developer Success As the definite goal 12

Slide 13

Slide 13 text

What does that mean? 13 With the idea of Business or Developer Success, we take the concept of Developer Experience in your organisation to the next level by also including the User Experience of the application that uses an API. Another factor, the Value Experience, refers to the exchange of values that make APIs sustainable and worthwhile for your organisation to invest in their development and maintenance.

Slide 14

Slide 14 text

Empathise with stakeholders 14

Slide 15

Slide 15 text

Who is going to use the API? 15

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

But… 17

Slide 18

Slide 18 text

You are not the consumer! 18

Slide 19

Slide 19 text

Techniques / Methods 19 Persona Empathic conversation Empathy map Extreme user Job shadowing What – How - Why Domain-Driven Design Event Storming Domain Storytelling

Slide 20

Slide 20 text

API Interaction Patterns 20 Different API interaction patterns exist to accommodate various use cases, requirements, and preferences of API consumers. These patterns provide different ways for clients to interact with APIs and can be chosen based on factors such as the nature of the application, the desired level of control and flexibility, and the specific goals of the API design.

Slide 21

Slide 21 text

API Interaction Patterns 21 Resource / Hypermedia Idea: Execute a specified set of methods on remote resources. Protocols: HTTP, gRPC is also possible for Resource Tunnel Idea: Call a procedure/command on a remote server as you would locally call a function in your programming language. Protocols: SOAP, XML/JSON-RPC, gRPC Query Idea: Formulate a query against a remote dataset as if the API were a database (cf. SQL). Protocols: HTTP (Query), GraphQL Event-Based Idea: Fetch events coming from a message broker Protocols: AMQP, MQTT, CloudEvents

Slide 22

Slide 22 text

22 Data definition

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

Master Data Management Adopting the idea of a Data Catalog 24

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

Data minimization Data observability As the declared goals 26

Slide 27

Slide 27 text

API definition 27 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: [email protected] license: name: MIT url: 'https://www.tldrelgal.com/mit' description: An API to provide news

Slide 28

Slide 28 text

Specifications 28 - ProtoBuf - GraphQL Schema

Slide 29

Slide 29 text

Challenges within API Design 29 - Long Running Operations - Paging / Filtering - Large Payloads

Slide 30

Slide 30 text

Establishing a design library and guidelines over time As the declared goal 30

Slide 31

Slide 31 text

API endpoint and backend implementation 31

Slide 32

Slide 32 text

API Design first or Protype first or Proxy first or Code first? 32

Slide 33

Slide 33 text

API Design First 33 This is where we sketch out the API endpoints, data structures, and use cases before we even think about code. The benefit? We get clarity on what our API needs to do and the best way to structure it, saving us time and headaches down the line.

Slide 34

Slide 34 text

Protype First 34 This method involves creating a mock-up or prototype of the API to test its functionality. This allows us to experiment, gather feedback, and adjust before committing to full-scale development. It’s all about learning quickly and adapting effectively.

Slide 35

Slide 35 text

Proxy First 35 The focus is on creating a façade that routes requests to existing services. This approach helps ensure smooth integration with legacy systems, making it easier to modernize incrementally.

Slide 36

Slide 36 text

Code First 36 While it might seem counterintuitive in an API First world, Code First isn't obsolete. It's just got a different focus - it's great for those times when the API’s requirements are clear from the start, and we want to get straight into coding.

Slide 37

Slide 37 text

API mediation 37 • 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 38

Slide 38 text

API Type Classification • Platform APIs • Service APIs 38

Slide 39

Slide 39 text

Platform APIs 39 • Use a framework the development team is proficient with • To create a first representation of the data • Transformation is maybe needed

Slide 40

Slide 40 text

40 Service APIs

Slide 41

Slide 41 text

API as a Product 41

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

Aggregations 43 • Use again a framework the development team is proficient with • To create aggregated or composed representation of data from Platform APIs • These APIs help to create a better experience for the user

Slide 44

Slide 44 text

Generating model classes for clients 44

Slide 45

Slide 45 text

Test by stakeholders 45

Slide 46

Slide 46 text

Based on the description 46

Slide 47

Slide 47 text

Description becomes a contract 47

Slide 48

Slide 48 text

Provide a Postman Collection of the API (product) 48

Slide 49

Slide 49 text

Contract Testing with Portman CLI https://github.com/apideck-libraries/portman 49

Slide 50

Slide 50 text

50 • Smoke • Load • Stress • Soak Performance Testing with k6

Slide 51

Slide 51 text

Delivery to a platform of choice 51

Slide 52

Slide 52 text

API Operations Pipeline 52

Slide 53

Slide 53 text

Reading material and recommendations 53 • https://linktr.ee/danielkocot • https://danielkocot.github.io • https://blog.codecentric.de • codecentric magazine „Der Softwerker“ • medium.com/@danielkocot In case of interest in more posts around API topics, follow me on LinkedIn or contact me.

Slide 54

Slide 54 text

codecentric AG Hoher Wall 15 44137 Dortmund Telefon: +49 (0) 151. 10 86 70 74 Daniel Kocot Head of API Experience [email protected] www.codecentric.de Innovative - Trustful - Competent - Pragmatic 54