Scribd
Upload
81 views

API Design

The document discusses REST (Representational State Transfer) and API design. It defines REST as an architectural style for distributed hypermedia systems, outlines its main concepts of resources, verbs, and representations, and provides examples of how HTTP methods map to CRUD operations on resources. The document also compares common API formats like REST, SOAP, GraphQL and gRPC.

Uploaded by

tabaali
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
81 views

API Design

The document discusses REST (Representational State Transfer) and API design. It defines REST as an architectural style for distributed hypermedia systems, outlines its main concepts of resources, verbs, and representations, and provides examples of how HTTP methods map to CRUD operations on resources. The document also compares common API formats like REST, SOAP, GraphQL and gRPC.

Uploaded by

tabaali
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 97

Spring 2021

By: Vahid Rahimian


API Design
System Analysis and Design

System Analysis and Design, Spring 2021, Sharif University


1

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
Agenda
• HTTP, REST Basics

By Vahid Rahimian
• REST API Design Guide
• SOAP, REST, GraphQL, and gRPC
• Which API Format?

2
HTTP, REST Basics

System Analysis and Design, Spring 2021, Sharif University


3

By Vahid Rahimian
Hypertext Transfer Protocol

System Analysis and Design, Spring 2021, Sharif University


(HTTP)
• A communications protocol

By Vahid Rahimian
• Allows retrieving inter-linked text documents
(hypertext)
• World Wide Web.

• HTTP Verbs
• HEAD GET /index.html HTTP/1.1
Host: myket.ir
• GET
• POST Browser Web Server
• PUT
HTTP/1.1 200 OK
• DELETE Content-Type: text/html
• TRACE
• OPTIONS <html><head>… 4
• CONNECT
System Analysis and Design, Spring 2021, Sharif University
Representational State Transfer (REST)

• A style of software architecture for distributed


hypermedia systems such as the World Wide

By Vahid Rahimian
Web.

• Introduced in the doctoral dissertation of Roy


Fielding
• One of the principal authors of the HTTP specification.

• A collection of network architecture principles


which outline how resources are defined and
5
addressed
System Analysis and Design, Spring 2021, Sharif University
REST and HTTP
• The motivation for REST was to capture the
characteristics of the Web which made the Web

By Vahid Rahimian
successful.

• URI Addressable resources


• HTTP Protocol
• Make a Request – Receive Response – Display Response

• Exploits the use of the HTTP protocol beyond HTTP


POST and HTTP GET
• HTTP PUT, HTTP DELETE
6
System Analysis and Design, Spring 2021, Sharif University
REST - not a Standard
• REST is not a standard

By Vahid Rahimian
• JSR 311: JAX-RS: The JavaTM API for RESTful Web
Services

• But it uses several standards:


• HTTP
• URL
• XML/HTML/GIF/JPEG/etc (Resource Representations)
• text/xml, text/html, image/gif, image/jpeg, etc
(Resource Types, MIME Types)
7
System Analysis and Design, Spring 2021, Sharif University
Main Concepts
Nouns (Resources)

By Vahid Rahimian
unconstrained
i.e., http://example.com/employees/12345

REST

Verbs Representations
constrained constrained 8
i.e., GET i.e., XML
System Analysis and Design, Spring 2021, Sharif University
Resources
• The key abstraction of information in REST is a
resource.

By Vahid Rahimian
• A resource is a conceptual mapping to a set of entities
• Any information that can be named can be a resource: a
document or image, a temporal service (e.g. "today's
weather in Los Angeles"), a collection of other resources, a
non-virtual object (e.g. a person), and so on

• Represented with a global identifier (URI in HTTP)


• http://myket.ir/games/clash-of-clans
9
System Analysis and Design, Spring 2021, Sharif University
Naming Resources
• REST uses URI to identify resources

By Vahid Rahimian
• https://myket.ir/games/
• https://myket.ir/games/clash-of-clans/
• https://myket.ir/games/clash-of-clans/comments/

• http://sharif.edu/classes
• http://sharif.edu/classes/cs40418-2
• http://sharif.edu/classes/cs40418-2/students

• As you traverse the path from more generic to more


specific, you are navigating the data 10
System Analysis and Design, Spring 2021, Sharif University
Verbs
• Represent the actions to be performed on resources

By Vahid Rahimian
• HTTP GET
• HTTP POST
• HTTP PUT
• HTTP DELETE

11
System Analysis and Design, Spring 2021, Sharif University
HTTP GET
• How clients ask for the information they seek.

By Vahid Rahimian
• Issuing a GET request transfers the data from the
server to the client in some representation

• GET http://taaghche.com/books
• Retrieve all books

• GET http://taaghche.com /books/ISBN-0011021


• Retrieve book identified with ISBN-0011021

• GET http://taaghche.com/books/ISBN-0011021/authors
• Retrieve authors for book identified with ISBN-0011021 12
System Analysis and Design, Spring 2021, Sharif University
HTTP PUT, HTTP POST
• HTTP POST creates a resource

By Vahid Rahimian
• HTTP PUT updates a resource

• POST http://admin.taaghche.com/books/
• Content: {title, authors[], …}
• Creates a new book with given properties

• PUT http://taaghche.com/books/isbn-111
• Content: {isbn, title, authors[], …}
• Updates book identified by isbn-111 with submitted properties

13
System Analysis and Design, Spring 2021, Sharif University
HTTP DELETE
• Removes the resource identified by the URI

By Vahid Rahimian
• DELETE http://admin.taaghche.com/books/ISBN-0011
• Delete book identified by ISBN-0011

14
System Analysis and Design, Spring 2021, Sharif University
Representations
• How data is represented or returned to the client for
presentation.

By Vahid Rahimian
• Two main formats:

• JavaScript Object Notation (JSON)

• XML

• It is common to have multiple representations of the


same data 15
System Analysis and Design, Spring 2021, Sharif University
Representations
• XML

By Vahid Rahimian
<COURSE>
<ID> CS40418-2 </ID>
<NAME> System Analysis and Design </NAME>
<INSTRUCTOR> Vahid Rahimian </INSTRUCTOR>
</COURSE>

• JSON
{
“id”: “CS40418-2”,
“name”: “System Analysis and Design”,
“instructor”: “Vahid Rahimian” 16
}
System Analysis and Design, Spring 2021, Sharif University
Representational State Transfer

By Vahid Rahimian
http://myket.ir/games/clash-of-clans
Client Resource

Description
Screenshots, Video
User Comments
...
Clash-of-Clans.html

The Client references a Web resource using a URL. A representation of the resource is returned (in
this case as an HTML document).
The representation (e.g., Clash-Of-Clans.html) places the client application in a state. The result of the
client traversing a hyperlink in Clash-Of-Clans.html is another resource accessed. The new
representation places the client application into yet another state. Thus, the client application changes
(transfers) state with each resource representation --> Representation State Transfer!
17
System Analysis and Design, Spring 2021, Sharif University
Architecture Style
Request HTTP GET

By Vahid Rahimian
(XML doc) URL 1 doGet()

Response HTTP Response

Web/Proxy Server
(XML doc)

doPost(id)
Request HTTP POST
(XML doc) URL 1 REST Engine
(locate resource
Response HTTP Response and generate
(JSON doc)
response) doDelete()

PO HTTP DELETE
(XML doc) URL 1

Response HTTP Response


(TEXT doc)

18
System Analysis and Design, Spring 2021, Sharif University
Real Life Examples
• Google Maps

By Vahid Rahimian
• Google AJAX Search API

• Amazon Web Services

• Trello API

19
System Analysis and Design, Spring 2021, Sharif University
REST and the Web
• The Web is an example of a REST system!

By Vahid Rahimian
• All of those Web services that you have been using all
these many years - book ordering services, search
services, online dictionary services, etc - are REST-
based Web services.

• Alas, you have been using REST, building REST services


and you didn't even know it.
20
Guide
REST API Design

System Analysis and Design, Spring 2021, Sharif University


21

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
Organize the API around resources
• Focus on the business entities that the
web API exposes. For example, in an

By Vahid Rahimian
e-commerce system, the primary
entities might be customers and
orders.
• Avoid requiring resource URIs more
complex
than collection/item/collection.
•
22
Define operations in terms of

System Analysis and Design, Spring 2021, Sharif University


HTTP methods
• GET retrieves a representation of the

By Vahid Rahimian
resource at the specified URI. The body
of the response message contains the
details of the requested resource.
• POST creates a new resource at the
specified URI. The body of the request
message provides the details of the new
resource. Note that POST can also be
used to trigger operations that don't
23
actually create resources.
Define operations in terms of

System Analysis and Design, Spring 2021, Sharif University


HTTP methods
• PUT either creates or replaces the

By Vahid Rahimian
resource at the specified URI. The body
of the request message specifies the
resource to be created or updated.
• PATCH performs a partial update of a
resource. The request body specifies the
set of changes to apply to the resource.
• DELETE removes the resource at the
specified URI. 24
HTTP methods
Define operations in terms of

System Analysis and Design, Spring 2021, Sharif University


25

By Vahid Rahimian
Conform to HTTP semantics:

System Analysis and Design, Spring 2021, Sharif University


Media Types
• In the HTTP protocol, formats are specified

By Vahid Rahimian
through the use of media types, also called
MIME types.

• For non-binary data, most web APIs support


JSON (media type = application/json) and
possibly XML (media type = application/xml).

• The Content-Type header in a request or


response specifies the format of the
representation. 26
Conform to HTTP semantics:

System Analysis and Design, Spring 2021, Sharif University


Media Types

By Vahid Rahimian
If the server doesn't support the media type, it
should return HTTP status code 415
(Unsupported Media Type).
27
Conform to HTTP semantics:

System Analysis and Design, Spring 2021, Sharif University


Media Types

By Vahid Rahimian
• A client request can include an Accept header that
contains a list of media types the client will accept from
the server in the response message.

• If the server cannot match any of the media type(s) listed,


it should return HTTP status code 406 (Not Acceptable).
28
Conform to HTTP semantics:

System Analysis and Design, Spring 2021, Sharif University


POST methods
• If a POST method creates a new resource, it returns HTTP status
code 201 (Created). The URI of the new resource is included in the

By Vahid Rahimian
Location header of the response. The response body contains a
representation of the resource.

• If the method does some processing but does not create a new
resource, the method can return HTTP status code 200 and include
the result of the operation in the response body. Alternatively, if
there is no result to return, the method can return HTTP status code
204 (No Content) with no response body.

• If the client puts invalid data into the request, the server should
return HTTP status code 400 (Bad Request). The response body can
contain additional information about the error or a link to a URI that
provides more details.
29
Conform to HTTP semantics:

System Analysis and Design, Spring 2021, Sharif University


PATCH methods
• With a PATCH request, the client sends a set of

By Vahid Rahimian
updates to an existing resource, in the form of a
patch document. The server processes the patch
document to perform the update.

30
Conform to HTTP semantics:

System Analysis and Design, Spring 2021, Sharif University


Async operations
• Sometimes a POST, PUT, PATCH, or DELETE
operation might require processing that

By Vahid Rahimian
takes a while to complete.
• If you wait for completion before sending a
response to the client, it may cause
unacceptable latency.
• If so, consider making the operation
asynchronous. Return HTTP status code 202
(Accepted) to indicate the request was
accepted for processing but is not
completed 31
System Analysis and Design, Spring 2021, Sharif University
Filter and paginate data
• GET requests over collection resources can
potentially return a large number of items.

By Vahid Rahimian
• You should design a web API to limit the
amount of data returned by any single
request.
• Consider supporting query strings that
specify the maximum number of items to
retrieve and a starting offset into the
collection.
32
Support partial responses for

System Analysis and Design, Spring 2021, Sharif University


large binary resources
• A resource may contain large binary fields, such
as files or images.

By Vahid Rahimian
• To overcome problems caused by unreliable and
intermittent connections and to improve
response times, consider enabling such
resources to be retrieved in chunks.
• To do this, the web API should support the
Accept-Ranges header for GET requests for large
resources.
• This header indicates that the GET operation
supports partial requests. The client application
can submit GET requests that return a subset of 33
a resource, specified as a range of bytes.
large binary resources
Support partial responses for

System Analysis and Design, Spring 2021, Sharif University


34

By Vahid Rahimian
Support partial responses for

System Analysis and Design, Spring 2021, Sharif University


large binary resources
• Also, consider implementing HTTP HEAD

By Vahid Rahimian
requests for these resources.
• A HEAD request is similar to a GET
request, except that it only returns the
HTTP headers that describe the resource,
with an empty message body.
• A client application can issue a HEAD
request to determine whether to fetch a
resource by using partial GET requests. 35
large binary resources
Support partial responses for

System Analysis and Design, Spring 2021, Sharif University


36

By Vahid Rahimian
Use HATEOAS to enable
navigation to related resources

System Analysis and Design, Spring 2021, Sharif University


37

By Vahid Rahimian
Versioning a RESTful web API

System Analysis and Design, Spring 2021, Sharif University


38

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
Versioning a RESTful web API
• URI Versioning

By Vahid Rahimian
https://adventure-works.com/v2/customers/3

• Query string versioning


https://adventure-works.com/customers/3?version=2

• Header versioning
39
• Media type versioning
Versioning a RESTful web API

System Analysis and Design, Spring 2021, Sharif University


40

By Vahid Rahimian
SOAP, REST,
GraphQL, and gRPC

System Analysis and Design, Spring 2021, Sharif University


41

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
SOAP
• Simple Object Access Protocol (SOAP)

By Vahid Rahimian
• A protocol for exchanging information
encoded in Extensible Markup
Language (XML) between a client and
a procedure or service that resides on
the Internet

42
System Analysis and Design, Spring 2021, Sharif University
SOAP
• SOAP is typically used with the Web

By Vahid Rahimian
Service Description Language (WSDL).

• WSDL describes how to structure the


SOAP request and response messages

43
Sample WSDL

System Analysis and Design, Spring 2021, Sharif University


44

By Vahid Rahimian
Sample WSDL (cont’d)

System Analysis and Design, Spring 2021, Sharif University


45

By Vahid Rahimian
Sample WSDL (cont’d)

System Analysis and Design, Spring 2021, Sharif University


46

By Vahid Rahimian
Sample SOAP Request

System Analysis and Design, Spring 2021, Sharif University


47

By Vahid Rahimian
Sample SOAP Response

System Analysis and Design, Spring 2021, Sharif University


48

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
REST
• Representational State Transfer

By Vahid Rahimian
• An architectural style devised by Roy
Fielding in his 2000 Ph.D. thesis.
• Use the standard HTTP methods, GET,
POST, PUT and DELETE, to query and
mutate resources represented by URIs
on the Internet.
49
REST

System Analysis and Design, Spring 2021, Sharif University


50

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
HATEOAS
• Hypermedia as the Engine of

By Vahid Rahimian
Application State
• a REST response can contain links that
describe operations or followup
workflow steps relevant to the given
resource.

51
REST can use HATEOAS

System Analysis and Design, Spring 2021, Sharif University


concept
• REST uses HATEOAS to define

By Vahid Rahimian
operations and workflow tasks that
are relevant to a resource

52
System Analysis and Design, Spring 2021, Sharif University
Sample REST Request
GET / HTTP/1.1

By Vahid Rahimian
Host: https://api.github.com/

accept: text/html,image/webp,image/png
accept-encoding: gzip, deflate, br
accept-language: en-US,en;q=0.9,fa;q=0.8
cache-control: no-cache
53
Sample REST Response

System Analysis and Design, Spring 2021, Sharif University


54

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
GraphQL
• GraphQL is a technology that came

By Vahid Rahimian
out of Facebook but is now open-
source specification.
• The underlying mechanism for
executing queries and mutations is
the HTTP POST verb.
• GraphQL requests can be sent via
55
HTTP POST or HTTP GET requests.
System Analysis and Design, Spring 2021, Sharif University
GraphQL
• as the name implies, GraphQL is

By Vahid Rahimian
intended to represent data in a graph.
• Instead of the columns and rows
found in a relational database or the
collection of structured documents
found in a document-centric database
such as MongoDB, a graph database is
a collection of nodes and edges. 56
System Analysis and Design, Spring 2021, Sharif University
GraphQL Query
• Unlike REST, in which the caller

By Vahid Rahimian
has no control over the structure of
the returned dataset (maybe just
‘fields’), GraphQL allows you to
define the structure of the returned
data explicitly in the query itself.

57
GraphQL Query

System Analysis and Design, Spring 2021, Sharif University


58

By Vahid Rahimian
GraphQL Query

System Analysis and Design, Spring 2021, Sharif University


59

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
GraphQL Request
• POST requests sent with the Content-

By Vahid Rahimian
Type header application/graphql must
have a POST body content as a
GraphQL query string.

60
System Analysis and Design, Spring 2021, Sharif University
GraphQL Request
• POST requests sent with the Content-

By Vahid Rahimian
Type header application/json must
have a POST body in the following
JSON format:

61
System Analysis and Design, Spring 2021, Sharif University
GraphQL Request
• In GET requests, the query, variables,

By Vahid Rahimian
and operation are sent as URL-
encoded query parameters in the
URL.

62
System Analysis and Design, Spring 2021, Sharif University
GraphQL Response
• The “data” field contains the result of

By Vahid Rahimian
your GraphQL request.
• The “extensions” field contains extra
metadata for the request with metrics
and trace information for the request.
• The “errors” field is a JSON list where
each entry has a "message" field that
describes the error. 63
Sample GraphQL Response

System Analysis and Design, Spring 2021, Sharif University


64

By Vahid Rahimian
Sample GraphQL Response

System Analysis and Design, Spring 2021, Sharif University


65

By Vahid Rahimian
Sample GraphQL Response (cont’d)

System Analysis and Design, Spring 2021, Sharif University


66

By Vahid Rahimian
Sample GraphQL Response

System Analysis and Design, Spring 2021, Sharif University


67

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
GraphQL Subscriptions
• Opens the door to asynchronous

By Vahid Rahimian
messaging.
• Query and mutation data exchange under
GraphQL is synchronous due to the
request-response pattern inherent in the
HTTP/1.1 protocol.
• However, GraphQL allows users to
receive messages asynchronously when a
specific event is raised on the server-side 68
GraphQL Subscriptions

System Analysis and Design, Spring 2021, Sharif University


69

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
gRPC
• A data exchange technology developed

By Vahid Rahimian
by Google and then later made open-
source.
• Like GraphQL, it's a specification that's
implemented in a variety of languages.
• Unlike REST and GraphQL, which use
text-based data formats, gRPC uses
binary format (increases performance) 70
System Analysis and Design, Spring 2021, Sharif University
gRPC Protocol Buffers
• gRPC uses the Protocol Buffers binary

By Vahid Rahimian
format.
• Both the client and server in a gRPC data
exchange shall have access to the same
schema definition
• By convention, a Protocol Buffers definition
is defined in a .proto file.
• The .proto file provides the "dictionary" by
which data is encoded and decoded to and
71
from the Protocol Buffers binary format.
gRPC

System Analysis and Design, Spring 2021, Sharif University


72

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
gRPC and HTTP/2
• In addition to using Protocol Buffers

By Vahid Rahimian
to encode data and thus increase
performance, gRPC has another
benefit.
• It supports bidirectional,
asynchronous data exchange. This is
because gRPC is based on the HTTP/2
protocol. 73
System Analysis and Design, Spring 2021, Sharif University
HTTP/2
• Unlike HTTP/1.1, which supports only a
request-response interaction over a single

By Vahid Rahimian
connection, HTTP/2 supports any number
of requests and responses over a single
connection.
• Connections can also be bidirectional.
• under HTTP/2, a client opens a
connection to a target server, and that
connection stays open until either the
client or server closes it.
• gRPC allows data streams as well. The 74
steam can emanate from the client or
from the server.
language format
gRPC schema in protocol buffer

System Analysis and Design, Spring 2021, Sharif University


75

By Vahid Rahimian
gRPC workflow

System Analysis and Design, Spring 2021, Sharif University


76

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
Sample ProtoBuff Message

By Vahid Rahimian
• In an application, you create a Test1 message
and set a to 150. You then serialize the message
to an output stream. If you were able to examine
the encoded message, you'd see three bytes:

77
System Analysis and Design, Spring 2021, Sharif University
Sample ProtoBuff Message

By Vahid Rahimian
• Now let's say you construct a Test4, providing
the values 3, 270, and 86942 for the repeated
field d. Then, the encoded form would be:

78
Sample gRPC Request

System Analysis and Design, Spring 2021, Sharif University


79

By Vahid Rahimian
Sample gRPC Response

System Analysis and Design, Spring 2021, Sharif University


80

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
API Communication
• a REST client written in Go can

By Vahid Rahimian
communicate with a REST server
written in Node.JS. Or, you can
execute a query or mutation from the
curl command.
• Same goes for GraphQL, gRPC, and
SOAP
81
Which API Format?

System Analysis and Design, Spring 2021, Sharif University


82

By Vahid Rahimian
System Analysis and Design, Spring 2021, Sharif University
SOAP: Pros
• SOAP can be implemented using a variety

By Vahid Rahimian
of protocols, not only HTTP but SMTP
and FTP as well.
• SOAP supports discovery via WSDL and
it's language agnostic.
• SOAP has been around for a while. There
is still a good deal of legacy SOAP
implementations that need to be
maintained. 83
System Analysis and Design, Spring 2021, Sharif University
SOAP: Cons
• SOAP can be considered a complex message
format with a lot of ins and outs to the

By Vahid Rahimian
specification.
• The verbose nature of XML which is the format
upon which SOAP is based, coupled with the
reliance on external namespaces to extend the
basic message format makes the protocol
difficult to manage.
• SOAP messages can get quite large.
• Moving bulky, text based, SOAP messages
between source and target takes a long time in
comparison to binary messaging protocols such 84
as gRPC
System Analysis and Design, Spring 2021, Sharif University
SOAP: Cons
• SOAP is a legacy protocol. While

By Vahid Rahimian
there’s a lot of maintenance work
to be done with those systems that
use it, new architectures are taking
a more modern approach to inter-
service communication.

85
System Analysis and Design, Spring 2021, Sharif University
REST: Pros
• REST is simple, well-known, and

By Vahid Rahimian
widely used.
• You make a call on a resource
represented by a URL on the Internet
using an HTTP verb and get a
response back in JSON or XML.
• Productivity under REST is almost
immediate.
86
System Analysis and Design, Spring 2021, Sharif University
REST: Cons
• REST is immutable in terms of the data

By Vahid Rahimian
structure of a response.
• Given the response/response aspect of
HTTP/1.1, REST can be slow.

87
System Analysis and Design, Spring 2021, Sharif University
GraphQL: Pros
• GraphQL is flexible and growing in

By Vahid Rahimian
popularity.
• The latest version of GitHub's API is
published using GraphQL. Yelp
publishes its API in GraphQL, as does
Shopify. The list continues to grow.
• The GraphQL specification covers every
aspect of API implementation, from
Scalars, Types, Interfaces, Unions,
88
Directives, …
System Analysis and Design, Spring 2021, Sharif University
GraphQL: Cons
• QraphQL is complex and hard to

By Vahid Rahimian
implement. While the specification
allows for customization, the basic
framework cannot be avoided. You
have to do things according to the
GraphQL way.
• REST, on the other hand, has a limited
rule set to follow.
89
System Analysis and Design, Spring 2021, Sharif University
GraphQL vs REST
• It's the difference between making a

By Vahid Rahimian
skateboard and making an automobile.
No matter what, you need four wheels as
well as a way to start and stop, but a
skateboard (REST) is far easier to make
and operate than an automobile
(GraphQL).
• It's a question of tradeoffs and making
sure the benefits of use outweigh the cost
of implementation. 90
• Once GraphQL is implemented, users
find it a better developer experience than
System Analysis and Design, Spring 2021, Sharif University
gRPC: Pros
• gRPC is exact and wicked fast.

By Vahid Rahimian
• It's become a de facto standard for
inter-service data exchange on the
backend.
• Bidirectional streaming capabilities that
are provided by HTTP/2 allow gRPC to
be used in situations where REST or
GraphQL can't even be considered.
91
System Analysis and Design, Spring 2021, Sharif University
gRPC: Cons
• Both client and server need to support the

By Vahid Rahimian
same Protocol Buffers specification. This
is a significant undertaking in terms of
version control.
• Under REST or GraphQL, one can add a
new attribute(s) to a resource (REST) or
type (GraphQL) without running much risk
of breaking the existing code. Making
such additions in gRPC can have a
detrimental impact. Thus, updates to the 92
.proto file need to be carefully
coordinated.
System Analysis and Design, Spring 2021, Sharif University
gRPC: Cons
• Another challenge is that HTTP/2 does

By Vahid Rahimian
not have universal support for public-
facing client-server interactions on the
Internet.
• Not all websites on the Internet support
HTTP/2.

93
System Analysis and Design, Spring 2021, Sharif University
gRPC: Cons
• gRPC is that it takes time to attain

By Vahid Rahimian
mastery.
• Some time can be saved by using the
protoc tool. protoc will auto-generate
gRPC client and server code according
to a particular programming language
based on a specific .proto file.
• It's useful for creating boilerplate code,
94
but doing more complex programming
requires a lot more work.
System Analysis and Design, Spring 2021, Sharif University
gRPC as a Backend Technology
• gRPC is best suited to situations where

By Vahid Rahimian
developers control both client and
server data exchange activities.
Typically such boundaries exist on the
backend. Hence, the prominence of
gRPC as a backend technology.

95
System Analysis and Design, Spring 2021, Sharif University
gRPC: Performance over Flexibility
• gRPC is a very particular API format

By Vahid Rahimian
that provides lightning-fast execution at
the expense of flexibility.
• Yet, if you have an application in which
nanoseconds count, gRPC includes
speed that is hard to match when using
REST or GraphQL.

96
System Analysis and Design, Spring 2021, Sharif University
By Vahid Rahimian
Any Questions?
Your time is limited, don’t waste it living someone else’s life

Steve Jobs, Stanford University speech, 2005


97

You might also like