API Experience

Transcript

1. API-Experience 1
2. codecentric AG Hoher Wall 15 44137 Dortmund Telefon: +49 (0) 151. 10 86 70 74 Daniel Kocot Head of API Experience daniel.kocot@codecentric.de www.codecentric.de Innovative - Trustful - Competent - Pragmatic 2
3. Daily Routine: Searching for data and creating new value for the organisation 3
4. API as a medium of transport 4
5. 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.
6. Consumer Journey 6 Discovery by the business and the development API Thinking Delivery to a platform of choice Usage
7. Searching for data and not in… Discovery 7
8. Design Thinking with APIs and data 8
10. Classical Design Thinking 10 Empathise Define Ideate Prototype Test
11. API Thinking 11 Empathise with stakeholders Data definition API definition API endpoint and backend implementation Test by stakeholders
12. Business & Developer Success As the definite goal 12
13. 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.
14. Empathise with stakeholders 14
15. Who is going to use the API? 15
16. Use Cases Describing why the API is needed and what systems are involved. 16
17. But… 17
18. You are not the consumer! 18
19. Techniques / Methods 19 Persona Empathic conversation Empathy map Extreme user Job shadowing What – How - Why Domain-Driven Design Event Storming Domain Storytelling
20. 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.
21. 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
22. 22 Data definition
23. 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?
24. Master Data Management Adopting the idea of a Data Catalog 24
25. Data Representation 25 Ø XML Ø JSON Schema Ø JSON for Linking Data (JSON-LD) Ø RDF (Resource Description Framework) Ø CBOR (Concise Binary Object Representation)
26. Data minimization Data observability As the declared goals 26
27. 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: daniel.kocot@codecentric.de license: name: MIT url: 'https://www.tldrelgal.com/mit' description: An API to provide news
28. Specifications 28 - ProtoBuf - GraphQL Schema
29. Challenges within API Design 29 - Long Running Operations - Paging / Filtering - Large Payloads
30. Establishing a design library and guidelines over time As the declared goal 30
31. API endpoint and backend implementation 31
32. API Design first or Protype first or Proxy first or Code first? 32
33. 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.
34. 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.
35. 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.
36. 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.
37. 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
38. API Type Classification • Platform APIs • Service APIs 38
39. Platform APIs 39 • Use a framework the development team is proficient with • To create a first representation of the data • Transformation is maybe needed
40. 40 Service APIs
41. API as a Product 41
42. Transformations 42 • Use Enterprise Integration Patterns • Apache Camel, Spring Integration, Apache Nifi, SaaS Service (e.g. Make), ...
43. 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
44. Generating model classes for clients 44
45. Test by stakeholders 45
46. Based on the description 46
47. Description becomes a contract 47
48. Provide a Postman Collection of the API (product) 48
49. Contract Testing with Portman CLI https://github.com/apideck-libraries/portman 49
50. 50 • Smoke • Load • Stress • Soak Performance Testing with k6
51. Delivery to a platform of choice 51
52. API Operations Pipeline 52
53. 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.
54. codecentric AG Hoher Wall 15 44137 Dortmund Telefon: +49 (0) 151. 10 86 70 74 Daniel Kocot Head of API Experience daniel.kocot@codecentric.de www.codecentric.de Innovative - Trustful - Competent - Pragmatic 54