20_api.slide

# API
Application Programming Interface



## what is API
API stands for application programming interface, which is a set of definitions and protocols for building and integrating application software.

_source: https://www.redhat.com/en/topics/api/what-are-application-programming-interfaces_


## client server architecture

## client server architecture
**basic client server architecture**

.image _concepts/20_api/Client-server-model.png _ 400
_source: https://upload.wikimedia.org/wikipedia/commons/thumb/c/c9/Client-server-model.svg/1200px-Client-server-model.svg.png_


## client server architecture
**request - response model**

.image _concepts/20_api/client-server-request-response.png _ 400
_source: https://darvishdarab.github.io/cs421_f20/assets/images/client-server-1-d85a93ea16590c10bed340dd78294d0d.png_

: more TODO: to add
: 1. https://intellipaat.com/blog/wp-content/uploads/2021/09/image-99.png
: 2. https://darvishdarab.github.io/cs421_f20/docs/readings/client_server/


## client server architecture

.video _concepts/20_api/request-flow/restful_api_request_flow.mp4 video/mp4 500 _

## RESTful API standard

## RESTful API standard
**intro**

Representational state transfer (REST) is a software architectural style that describes the architecture of the Web.

_source: https://en.m.wikipedia.org/wiki/Representational_state_transfer_


## RESTful API standard
**characteristics of REST**

https://www.scrapingbee.com/blog/six-characteristics-of-rest-api/


## RESTful API standard
**anatomy of API request and response**

TODO: need to find a diagram or make one

: show these parts using postman


////////////////////////////////////////////////////////////////////////
## RESTful API standard: request

## RESTful API standard
**request anatomy**
- method
- path: url/uri/resource
- request body
- headers


## RESTful API standard
**request: method**

indicates the type of the request operation: CRUD (Create Read Update Delete) operations and more
- POST: creating a new resource
- GET: get details of an existing resource
- DELETE: deleting an existing resource
- PUT: updating an existing resource, updates the complete record (all fields)
- PATCH: updating an existing resource, by passing only the fields to be updated
- and more uncommon methods

## sql vs rest
    
// TODO: compare these methods with CRUD 
// SQL  vs  REST
// table    resource
// INSERT   POST
// SELECT   GET
// DELETE   DELETE
// UPDATE   PUT/PATCH


## RESTful API standard
**request: method**

Idempotent REST APIs

https://restfulapi.net/idempotent-rest-apis/

## RESTful API standard
**request: path**

path includes uri (universal resource identifier)

example: in www.example.com/api/student/123 
- "/api" is the optional prefix to indicate that this is a API URL
- "/student" identifies the resource and is called the URI (in general)
- "/123" id

// TODO: (at a later slide) add examples of how path will be for different methods

## RESTful API standard
**request: body**

data associated with the request 

example (json): 

    {"name":"rohit","addr":"","marks":300}

: data can be of any format (example, json, plain text, html, etc) as long as the client and server agrees upon
: .
: server can also accept data in multiple formats, in which case client should indicate the data type using the content-type header.

## RESTful API standard
**request: headers** 

key value pairs used to store
- metadata
- user authentication
- and more

example: 

    Content-type: application/json

- there are many common headers (like above), 
- the server and client can define their own headers, as long as they both understand the purpose of it.

////////////////////////////////////////////////////////////////////////
## RESTful API standard: response

## RESTful API standard
**response anatomy**

- status code
- response body
- headers


## RESTful API standard
**response: status code**

numerical code indicating the status of the request process
- 2xx: success
- 4xx: client side error
- 5xx: server side error

.link https://developer.mozilla.org/en-US/docs/Web/HTTP/Status and more 

## RESTful API standard
**response: body**

response data sent to the client by the server

example (json): 

    {"name":"rohit","addr":"","marks":300}

: data can be of any format (example, json, plain text, html, etc) as long as the client and server agrees upon


## RESTful API standard
**response: headers**

key value pairs used to store
- metadata
- user authentication
- and more

example: 

    Content-type: application/json
    Content-type: application/xml


## RESTful API standard
**further read**

.link https://blog.uptrends.com/technology/the-anatomy-of-an-api-call/ The anatomy of an API call
.link https://www.geeksforgeeks.org/rest-api-introduction/  
.link https://www.youtube.com/watch?v=7YcW25PHnAA Video: REST API concepts and examples
.link https://www.youtube.com/watch?v=lsMQRaeKNDk Video: What is a REST API?


////////////////////////////////////////////////////////////////////////
## api designing using swagger

## api designing using swagger
**what is swagger**

## api designing using swagger
**swagger editor**
https://editor.swagger.io/

## api designing using swagger
**example**


////////////////////////////////////////////////////////////////////////
## api server programming using net/http package

1helloworld.go
2server.go


## api server programming using gorilla mux package
## api server programming using other 3rd party packages
## api client programming using net/http package