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 Landscape:
https://apilandscape.apiscene.io/
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
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 ?
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.
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
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
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