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/

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