Scribd
Upload
3 views

RESTful API (with RoR)

The document provides an introduction to RESTful APIs using Ruby on Rails, covering key concepts such as the definition of APIs, their necessity, and how to build them. It discusses authentication methods, particularly the OAuth2 protocol, and outlines performance enhancement strategies for APIs. Additionally, it includes information on API documentation and common HTTP status codes.

Uploaded by

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

RESTful API (with RoR)

The document provides an introduction to RESTful APIs using Ruby on Rails, covering key concepts such as the definition of APIs, their necessity, and how to build them. It discusses authentication methods, particularly the OAuth2 protocol, and outlines performance enhancement strategies for APIs. Additionally, it includes information on API documentation and common HTTP status codes.

Uploaded by

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

Introduction to

RESTful API (with RoR)


December 1, 2018
Content

1. What is API?
2. Why API is needed?
3. How to Build RESTful API?
4. OAuth2 Protocol
5. API Performance Enhancement
6. API Documentation
7. Some HTTP Status Code
What is API?

● API = Application Programming Interface


● Application Application
Why API is needed?

● Communication with application and application (server / client)


● Mobile Apps
● Affiliates
● Information sharing
● Multiple clients with one server
● Service providers (payment gateway, ...)
How to Build RESTful API?

Brief History of RESTful API

● RESTful API can specify content-type (json, html, xml, ...)


● RESTful API was found in 2000
● Before RESTful API ⇒ SOAP (Simple Object Access Protocol) ⇒ limited content-type (only xml)
How to build RESTful API? (Cont’)

Use correct HTTP verbs

Action HTTP Verb Endpoint Controller#Action

Read Collection of Records GET /operators operators#index

Read One Record GET /operators/:id operators#shows

Create Record POST /operators operators#create

Update Record PUT / PATCH /operators/:id operators#update

Delete Record DELETE /operators/:id operator#destroy


API Authentication & Authorization

● Authentication vs Authorization
● Old-School Authentication
○ Embed username and password in the every requested endpoints
■ (e.g. /operators?username=xxx&password=xxx)
○ URLs can be copied and shared to others
○ URLs most likely be logged in the server log
● OAuth2 ⇒ a popular protocol for building a secured API
○ Use access token to authorize the application
○ Embed access token in the header
○ Most servers will not write header logs
○ Can set expired time of the access token
○ RoR gem ⇒ doorkeeper
OAuth2 Flow

● Exchange credential for access token

POST /oauth/token

Parameters: { username: ‘xxx’, password: ‘xxx’, grant_type: ‘password_flow’ }

Response: { token: ‘122adf2e23dwsg1278z’ }


OAuth2 Flow (Cont’)

● Embed access token in the header when sending request

Header: (Authorization: ‘Bearer 122adf2e23dwsg1278z’ )

GET /operators
OAuth2 Flow (Cont’)

● Some APIs are not related to user


○ E.g. Forget Password, …
○ Use client API_KEY and API_SECRET as credentials
○ Exchange the credentials for access token

POST /oauth/token

Parameters: { client_id: ‘xxx’, client_secret: ‘xxx’, grant_type: ‘client_credential’ }

Response: { token: ‘1345sadrfa24jk654d’ }


API Performance Enhancement

● Allow IPs in whitelist


● Deny IPs in blacklist
● Limit access rate
● Filter parameters (esp. from POST / PUT Request)
● Paginate result
● API namespacing and versioning
● Caching
API Documentation

● Purpose of each API endpoint


● Display request endpoint with HTTP verb
● Describe request parameters name with their purposes and data type
● Display whether each parameter is required or optional
● Example of request and response payload with full HTTP header, status code, and
response body
● Consider which API endpoints should be displayed in public documentation and which
should be displayed in internal documentation
● RoR gem ⇒ rspec_api_documentation
Some HTTP Status Code

● Successful Response (200 series)


○ 201 Created
○ 200 OK
○ 204 No Content
● Failed Response (400 series)
○ 400 Bad Request
○ 401 Unauthorized
○ 403 Forbidden
○ 404 Not Found
○ 422 Unprocessable
○ 429 Too Many Request
References

● https://searchmicroservices.techtarget.com/definition/RESTful-API
● https://www.mulesoft.com/resources/api/what-is-rest-api-design
● https://blog.readme.io/the-history-of-rest-apis/
● https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
Questions & Answers

You might also like