APIs are at the heart of the modern software development world. Whether we author a distributed system, a microservices-based application, or a simple client-server n-tier application - our system will most probably expose an API at its core. APIs are a means to expose the functionality of a particular component to its users. Unsurprisingly, many formats for APIs have existed over the years, with the industry setting around RESTful APIs as the de-facto standard, with gRPC growing in popularity. Join me in this session, as I review today's most popular API formats and their relative strengths and weaknesses. From REST, through OpenAPI, via gRPC and to the rising star of AsyncAPI - we'll explain how these API formats work and the tools they employ and offer some guidance as towards when we should use each. At the end of this session, you'll have a good familiarity with these formats, and you'll be in a much better position to choose between them.

1. API Design in the Modern Era
Eran Stiller
Chief Technology Officer, CodeValue
erans@codevalue.net
@eranstiller
https://stiller.blog
https://codevalue.net

2. What Choice Do We Have When Designing an API?
2

3. There Are Multiple
Choices!
3

4. Agenda
▪ REST
▪ OpenAPI
▪ gRPC
▪ AsyncAPI
4

5. About Eran
Eran Stiller
▪ @eranstiller
▪ CTO & Founder at CodeValue
▪ Software architect, consultant and instructor
▪ Microsoft Regional Director & Azure MVP
▪ Founder of Azure Israel Meetup
5

6. Azure Israel
▪ https://www.meetup.com/AzureIsrael
6

7. REST
8

8. REST
▪ Representational State Transfer (REST)
▪ Largely based on the HTTP protocol
▪ Web APIs that conform the REST are called RESTful APIs
▪ An architecture style, not standard
▪ Various interpretations and guidelines exist
▪ No absolute right and wrong
▪ Only good and not-so-good practices ☺
12

9. Richardson Maturity Model
Level 3:
Hypermedia
Level 2:
HTTP Verbs
Level 1: Resources
Level 0: The Swamp of POX
13

10. Hypermedia Control (HATEOAS)
14
{
"departmentId": 10,
"departmentName": "Administration",
"locationId": 1700,
"managerId": 200,
"links": [
{
"href": "10/employees",
"rel": "employees",
"type" : "GET"
}
]
}

11. Hypermedia Control (HATEOAS)
▪ Implementing HATEOAS is hard
▪ Some implementations available
▪ JSON API
▪ ODATA
▪ HAL
▪ Siren
▪ JSON Hyper-Schema
15

12. Demo
OData
16
https://youtu.be/hgW6LXyxw00
(Hebrew)

13. What If You Don’t Implement HATEOAS?
17

14. OpenAPI
18

15. OpenAPI – an Interface Definition Language (IDL)
▪ A standard means to convey the interface shape out-of-band
19

16. OpenAPI – an Interface Definition Language (IDL)
20
openapi: 3.0.0
info:
title: Library API
version: 1.0.0
servers:
- url: http://localhost:8080
paths:
/api/books/{bookId}:
get:
tags:
- Books
operationId: getBook
parameters:
- name: bookId
in: path
required: true
style: simple

17. 21
parameters:
- name: bookId
in: path
required: true
style: simple
explode: false
schema:
type: integer
format: int32
x-position: 1
responses:
"200":
description: The requested book
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
"404":
description: The requested book was not found
x-swagger-router-controller: Books

18. Expected Client Usage
1. Decide which OpenAPI URL path template to use
2. Calculate the parameter values to use (if any)
3. Plug the parameter values into the URL path template
4. Send an HTTP request
22

19. Design Approach
Code-First vs. Contract-First
23

20. Design Approach
Entity-Oriented vs. Procedure-Oriented
24

21. Tooling Support
▪ Code generators
▪ Client & Server
▪ Test generators
▪ Documentation generators
▪ API Gateway support
25

22. Demo
OpenAPI
26
https://youtu.be/N5LLDKw_5bo
(Hebrew)

23. GraphQL – Noteworthy Alternative
28

24. gRPC
29

25. gRPC – an Interface Definition Language
▪ Similar, but different, to OpenAPI
▪ A modern alternative to RPC frameworks of the past
▪ DCOM
▪ WCF
▪ XML-RPC
▪ JSON-RPC
▪ …
▪ Quickly becoming the de-facto standard in RPC
30

26. Proto Files
31
syntax = "proto3";
package helloworld;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply) {}
}
message HelloRequest {
string name = 1;
}
message HelloReply {
string message = 1;
}

27. Proto Files – Streaming
32
syntax = "proto3";
package hellostreamingworld;
service MultiGreeter {
rpc sayHello (HelloRequest) returns (stream HelloReply) {}
}
message HelloRequest {
string name = 1;
string num_greetings = 2;
}
message HelloReply {
string message = 1;
}

28. Demo
gRPC
34
https://youtu.be/JCueeqc6-BA
(Hebrew)

29. gRPC Considerations
▪ Contract-first
▪ Lots of code/test/document generation support
▪ API Gateway support
▪ Not at the level of OpenAPI (yet)
▪ Typically modeled with a procedural orientation
▪ Can be used in a constrained entity driven model
▪ Allow mapping to REST with “grpc-gateway”
36

30. Mapping to REST with Annotations
37
syntax = "proto3";
import "google/api/annotations.proto";
message StringMessage {
string value = 1;
}
service YourService {
rpc Echo(StringMessage) returns (StringMessage) {
option (google.api.http) = {
post: "/v1/example/echo"
body: "*"
};
}
}

31. AsyncAPI
38

32. What About Asynchronous Communications?
39

33. Traditionally – Do It Yourself
▪ Model the messages (how?)
▪ Publish the model (how?)
▪ Convey protocol decisions (how?)
▪ Manage versions (how?)
40

34. AsyncAPI to the Rescue
▪ An attempt to standardize out-of-band conveying of data
▪ Like OpenAPI for asynchronous communication
▪ Does not assume any tech stack
▪ Bring your own protocol
▪ Bring your own schema
▪ Bring your own security mechanism
▪ The more standard it is, the more likely tools will support it
▪ Defines two operation types a service can support
▪ Publish
▪ Subscribe
▪ Code-First & Contract-First
41

35. Demo
AsyncAPI
42
https://youtu.be/c4NKi9hO5pk
(Hebrew)

36. Warning – Here Be Dragons!
44

37. Takeaways
▪ REST is more than HTTP APIs
▪ OpenAPI allows simplifying work with HTTP APIs
▪ OpenAPI assumes HTTP & JSON
▪ Does not coerce REST semantics
▪ GraphQL is an interesting alternative
▪ gRPC is a modern RPC-style framework
▪ AsyncAPI attempts to close the gap on asynchronous programming
▪ Still in pre-alpha state for most technologies/platforms
45

38. Additional Resources
▪ Source code
▪ https://github.com/estiller/modern-era-apis
▪ Demo videos
▪ https://www.youtube.com/playlist?list=PLnimcNcOqCXizxqWEceI0IH3-bDpCJzkC
▪ Official Websites
▪ https://www.openapis.org/
▪ https://grpc.io/
▪ https://www.asyncapi.com/
▪ Articles
▪ https://cloud.google.com/blog/products/api-management/understanding-grpc-openapi-and-
rest-and-when-to-use-them
▪ https://medium.com/apis-and-digital-transformation/openapi-and-grpc-side-by-side-
b6afb08f75ed
▪ https://www.freecodecamp.org/news/rest-is-the-new-soap-97ff6c09896d/
46

39. Eran Stiller
erans@codevalue.net
@eranstiller
https://stiller.blog