Apidays Paris 2023 - API design first: A case for a better language, Emmanuel Bastien

Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies
December 6, 7 & 8, 2023

API design first: A case for a better language
Emmanuel Bastien

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Lands

Transcript

1. API design first A case for a better language
2. Who am I? Emmanuel Bastien Polyglot software engineer and senior leader with exposure to a wide range of industries, from travel to telecoms, business consulting and energy marketing. https://ebastien.name https://github.com/ebastien https://www.linkedin.com/in/ebastien
3. Our journey to API design first
4. API as a Product
5. Digital product design Design Development
6. Incremental API design From a by-product of the server implementation To a working design document “How do I distribute an API contract?” “How do I craft an API contract?”
7. What is a web API contract? JSON HTTP JSON Schema ?
8. HTTP contracts Hypermedia Unified interface Resources Transport 3. 2. 1. 0.
9. Why OpenAPI? Swagger was born as a data exchange format for API descriptions.
10. Distributed development 󰞅󰠁󰟲 TypeScript 󰞅󰠁󰟲 Python 󰞅󰠁󰟲 Go API
11. API design workflow API Design Software Component
12. API design track 1. Sketch solutions, putting aside some level of details. 2. Validate running prototypes, without investing development effort. 3. Submit for review by peers, for instance as a "pull request" on GitHub. 4. Make corrections and merge for release to software components.
13. Concrete examples ✔ As a customer, I want to order a coffee so that the coffee shop can prepare my drink. ✔ As a customer, I want to be able to change my drink to suit my tastes. ✔ As a customer, I want to be able to pay my bill to receive my drink. ✔ As a barista, I want to see the list of drinks that I need to make, so that I can serve my customers. ✔ As a barista, I want to check that a customer has paid for their drink so that I can serve it. ✔ As a barista, I want to remove drinks I have made from the pending list so that I don't make duplicates.
14. The shape of an abstraction
15. Syntax
16. Alternative abstractions ✔ Code-first ✔ Graphical OpenAPI editor Stoplight ✔ JSON preprocessor Dhall, CUE ✔ Domain specific languages TypeSpec, Oxlip, Taxi…
17. “Object-oriented” design with TypeSpec Open Source (MIT) Extensible interface description language Built-in support for REST, GraphQL, gRPC Not specific to OpenAPI definitions Syntax inspired by mainstream object-oriented languages https://microsoft.github.io/typespec
18. “Object-oriented” design with TypeSpec
19. “Object-oriented” design with TypeSpec
20. “Functional” design with Oxlip Open Source (Apache 2.0) Small interface description language Dedicated to REST APIs (JSON/HTTP) Targeting feature parity with OpenAPI Syntax and evaluation inspired by functional languages https://www.oxlip-lang.org
21. “Functional” design with Oxlip
22. “Functional” design with Oxlip
23. Closing words
24. References REST In Practice - https://www.oreilly.com/library/view/rest-in-practice/9781449383312 How to GET a cup of coffee - https://www.infoq.com/articles/webber-rest-workflow Stoplight - https://stoplight.io Dhall - https://dhall-lang.org CUE - https://cuelang.org TypeSpec - https://microsoft.github.io/typespec Smithy - https://smithy.io Taxi - https://taxilang.org Oxlip - https://www.oxlip-lang.org Examples - https://github.com/oxlip-lang/example-restbucks