7 of 35

What is a service?

A service is a program that runs in the background and listens for / responds to certain kinds of messages.
Performs automated tasks, responds to hardware events, or listens for data requests from other software.
In a user's operating system, these services are often loaded automatically at startup, and run in the background, without user interaction

On a Mac: lsof -i -P | grep -i "listen"

On a Windows: Control Panel > Administrator Tools > Service Icon

8 of 35

What is a port?

Copied directly from Cloudflare’s website:

Ports are software-based and managed by a computer's operating system
Each port can be associated with a specific process or service
Ports allow computers to easily differentiate between different kinds of traffic from the same IP address: emails go to a different port (25) than webpages (80), for instance, even though both reach a computer over the same Internet connection.
Some ports are reserved and some are open

9 of 35

What is an http://127.0.0.1?

127.0.0.1 is a special IP address – also referred to as “localhost” – which is a reference to your local computer.
Doesn't let computers communicate with other devices as a real IP address does (it’s private, not public)
On most operating systems, the following two addresses can be used interchangeably:

10 of 35

Outline

Roadmap
Ports and Services
Designing REST Interfaces
Activity

11 of 35

Recall from Week 6

API → “Application Programming Interface”

A set of rules that you have to follow to interact with a piece of software

Web API

An API that you access via HTTP protocol. Offers a systematic way to:

Create update, read, and delete resources over the internet
Expose parts of your database to third party clients
Allow a web client (or any client) to take advantage of resources distributed across providers, servers, organizations, etc.

12 of 35

Who uses Web APIs?

Everyone!

Allows organizations to systematically expose parts of their data / resources for authorized users to consume simply and easily.
How well you design your API – how easy it is to use, documentation, etc. – determines whether it gets used at all (which impacts the success of your project).
It’s useful to study how other companies and organizations have designed their APIs (e.g., Spotify, Twitter, Yelp, NASA, NYC Open Data Portal, etc.)

Learn from them!

13 of 35

Standardizing HTTP Interfaces

In the early days of the web, there were no standards, so everyone build their Web APIs differently.
This meant that each time a client wanted to interoperate with a different system, they would have to learn a new set of rules, conventions, etc.

14 of 35

A variety of different solutions to this problem

SOAP (1998). Simple Object Access Protocol. Developed by Microsoft. Requests to formulate queries issued via XML; can get complicated to formulate, but still used.
REST (2000). Representational State Transfer Protocol. Developed by Roy Fielding. Today’s topic. A very widely used approach (at this point in time).
GraphQL (2015). Developed by Facebook and open sourced in 2015. Allows you request more fine-grained subsets of relational resources (see docs)

15 of 35

Web APIs & the REST Architecture

One popular way of building a Web API is by following the REST architecture guidelines. Some facts about REST:

REST: Stands for REpresentational State Transfer
An architecture style or design criteria. Not a standard or a language
Stateless, client-server, cacheable communications protocol
Use HTTP requests to post, read, and delete data.
Lightweight
Nouns as URI, verbs as HTTP method

Source: https://www.slideshare.net/cebartling/rest-web-services

16 of 35

Resource-Oriented Architecture

Resource-oriented�About storing, manipulating, and querying resources (nouns)
Addressability �Resources are identified by URIs (which are also called endpoints)
Statelessness�No connection state maintained between REST invocations
Connectedness�Resources should link together in their representations
Uniform interface

Methods (verbs): HTTP GET, PUT, POST, DELETE, HEAD, OPTIONS
HTTP status codes

17 of 35

1. Resource

Noun. The thing that is being represented by data / a document

Can be a physical object(s) (something you buy on Amazon)�or an abstract concept (likes)
Every resource has at least one name
Resources can be list resources (called containers) �or detail resources:

Container/List Resource: http://127.0.0.1:5000/api/posts
Detail Resource: http://l27.0.0.1:5000/api/posts/6

Source: https://www.slideshare.net/cebartling/rest-web-services

Note the plural convention for detail resources

18 of 35

1. Resource

Example of a resource: https://csci344-hw07.herokuapp.com/api/posts/235

{

"image_url": "https://picsum.photos/600/430?id=908",

"user": {

"first_name": "Timothy",

"last_name": "Myers",

"username": "timothy_myers",� ...

"caption": "Spend catch ready administration success..."

"likes": 853

}

19 of 35

2. Addressability

Endpoints: Every resource has an address, denoted by a URI (uniform resource identifier)

Example: https://csci344-hw07.herokuapp.com/api/posts/235

The URI enables the client to perform “CRUD” operations

create new resources
update the resource
read / obtain useful information about the state of a resource
delete the resource

Source: https://www.slideshare.net/cebartling/rest-web-services

20 of 35

2. Addressability: Examples

Container/List Resource (create and read):

�Detail Resource (update, delete):

https://csci344-hw07.herokuapp.com/api/posts/235
Note that not all container resources make their detail resources accessible

21 of 35

3. Statelessness

Means that there is no “stored context” or memory across transactions:

Each request from the client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server.
The client (i.e. your app) is responsible for:

storing and handling all application state related information on client side
sending any state information to the server whenever it is needed

Source: https://restfulapi.net/statelessness/

22 of 35

4. Connectedness

You should be able to connect / discover relationships between resources from the resource representation. Example (Comment):

{

"text": "Text text text....",

"post_id": 6,

"user": {

"first_name": "Emily",

"last_name": "Terry",

"username": "emily_terry",

"email": "emily_terry@gmail.com",

...

}

Source: https://www.slideshare.net/cebartling/rest-web-services

23 of 35

5. Uniform Interface

“Interface” — refers to the way we interact with and modify resources.

�In REST All resources are created, updated, read, and deleted in the same way, using the HTTP protocol methods (verbs), which are defined in the header of the request. Here are some of them:

GET
POST
PUT
PATCH
DELETE

Source: https://www.slideshare.net/cebartling/rest-web-services

24 of 35

GET

Retrieves / reads a resource (or container of resources) from an address on a server

�NEVER modify a resource using the GET method – you can do it (technically) but you never should.

25 of 35

POST

Creates a NEW resource on a server; usually done by posting to the container endpoint:

26 of 35

PUT & PATCH

PUT: Replaces a single resource on a server

PATCH: Updates part of a resource on a server

27 of 35

DELETE

Permanently deletes a resource on a server

28 of 35

HTTP Status Codes

Use the status codes to help your client understand success and failure. Here is a list of them.

For HW1 and HW2...

Use a 201 status code if POST is used to successfully create a resource
Use a 200 status code for a valid request (most other requests)
Use a 400 status code if user posted a bad request
Use a 403 status code if a resource is forbidden (you don’t have access)
Use a 404 status code if a resource cannot be found
Use a 500 status code if the server encountered an error

29 of 35

References / Credits

Much of this REST overview was derived from:

RESTful Web Services�https://www.slideshare.net/cebartling/rest-web-services

Christopher Bartling
Nick Spilman
Kevin Hakanson

30 of 35

Clients

You can access a REST API via many different clients (including):

Postman (Week 6 + Today)
Using JavaScript on a web browsers (Weeks 6-10)
via Python / Flask (last Friday)
cURL
native apps
And more!

31 of 35

Accessing Third Party Web APIs

32 of 35

Recall: Accessing a Web API

Typically, in order to use a Web API, you typically need to register with the API provider and obtain an access token (which is typically kept secret).
This enables the provider to track who is using their API and for what purposes. Platforms might also charge for their data services (i.e. Google), so people’s bank accounts are often tied to their API key
An API key can be passed as a query parameter (not that common) or as a HTTP header (more common)

33 of 35

Passing data via a request using HTTP

There are several different ways that data can be passed TO a server via HTTP to formulate a request

Through query string parameters (which follow the “?”) after a URL

For GET requests

Through the URL Path (we’ll look at this next week)
Through the body (Wednesday)

For POST, PATCH, and PUT requests

Through metadata embedded in the HTTP request header

Like the access token

34 of 35

Outline

Roadmap
Ports and Services
Designing REST Interfaces
Activity

35 of 35

Design a REST API for a Ticketing Service

You are designing a service to facilitate the purchase of tickets for various events (concerts, sporting events, plays, etc.). You need a way for your customers to browse various events, check out the venue, pick seats, and pay (ignore the login / registration workflow). Design a REST API to facilitate this.

What will the endpoints be?
For each endpoint:

What methods need to be supported (GET, POST, PUT, PATCH, DELETE)?
For GET requests: What parameters need to be supported (which are required and which are optional)?
For POST/PUT/PATCH requests: What data should be required in the payload?