Module 5: API Design

Rey Benjamin M. Baquirin, MSCS

API Architecture
SOAP (Simple Object Access Protocol)
• Used to be a very specific type of API access. Developers were able to
flexibly use it in various situations though, so since v1.2, the acronym was
dropped. But originally it was only a protocol.
• SOAP is focused on reliability, standard extensions for adding functionality
to the protocol, and generate code, exchange of data between different
platforms made from different PLs.

REST (Representational State Transfer)

• Designed specifically for working with media components, objects, and
files.
API Architecture

SOAP REST
Uses service interfaces to deliver Uses URL/URI to access components
functionality
Needs more bandwidth Needs less bandwidth
XML only XML, HTML, JSON
SOAP cannot implement REST RESTful APIs can make use of SOAP
More secure Less secure
API Design
• REST is more commonly used as it is more developer-friendly.

General Steps on designing an API

1. Identify resource(s) you want to be available through the API
2. Assign URLs to those resource
3. Identify the actions the client is allowed to do on the resources
4. Curate all data required to accomplish the actions in #3 and what
format they should be in
API Design
Using the Pizza Parlor example:

1. Resources: Order, Menu, Pizza, Customer

2. URLs: In REST standards, every resource has two URL patterns
a) Resource
b) Resource + UID
e.g. /orders
/order/<order_number>

These are called end-points. E.g. https://pizzaparlor.com/<endpoint>

API Design
3. ACTIONS: This can be developer dependent. But RESTful standards
usually:
e.g. Endpoint 1 (/orders): List (GET) existing orders and Create (POST)
new ones
Endpoint 2 (/orders/<order_number>): Retrieve (GET), Update
(PUT), Cancel (DELETE) orders

4. FORMATS: JSON
API Design

METHOD ENDPOINT ACTION

GET /orders List all existing orders
POST /orders Create a new order
GET /orders/1 Get details for order #1
GET /orders/2 Get details for order #2
PUT /orders/2 Update order #2
DELETE /orders/2 Cancel order #2
API Design
API Design
API Design
API Design
API Design
ASSOCIATING DIFFERENT RESOURCES: There are many permutations of
objects we can indicate to get data we want, as such, there should be
standards of how to link resources together

e.g. How to link an order endpoint to a specific customer

RESTful Standards: a.) Use 1 endpoint

b.) Link 2 endpoints
API Design
API Design
Query String: component of a URL that allows for searching
e.g. https://pizzaparlor.com/orders?key=value

Query strings are very important to sift through records in the

database. How many orders had pineapple toppings?
RESTful Standards: Use ampersand (&) to separate query parameters
e.g. https://pizzaparlor.com/orders?topping=pineapple&crust=thin
e.g. https://pizzaparlor.com/orders?page=2&size=100