Eslam Hamouda

CS Student - Software Developer

@EslaMx7

www.eslamx.com

 

RESTful Web API
Design Guidelines

API

Web Service

Web API

Developers as Customers

Why Web API ?

REST

  • REpresentational

  • State

  • Transfer

REST is not a ?

  • Framework

  • Technology

  • even a Standard Specification

It is...

Software Architecture Style

for creating web services.

But... With Some Constraints

  1. Client-Server
  2. Statelessness
  3. Cacheable
  4. Layered system
  5. Code on demand (optional)
  6. Uniform interface

1- Client-Server

Separates user interface concerns from data storage concerns

HTTP

2- Statelessness

Each request from any client contains all the information necessary to service the request

Client: Hi, Server
Server: Who Are You ?
Client: I'm Eslam!
Server: OK! I Know you, Hi Eslam ;)
Client: What is my schedule today ?
Server: Who Are You ?
Client: I'm the one who just saied Hi, Server !
Server: Nope, we didn't met before!, Who Are You ?
Client: I'm Eslam! is that Okay for you?
Server: Hi Eslam, Sorry my memory is not plugged-in.
Client: I'm Eslam!, what is my schedule for today ?
Server: You have an AWESOME session at CAT Scope Event.
Client: Thank You Server!
Server: Who Are You ?

Game... ?

3- Cacheable

- Clients can cache responses.

- Responses must therefore, implicitly or explicitly, define themselves as cacheable, or not.

4- Layered System

A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Intermediary servers may improve system scalability by enabling load balancing and by providing shared caches.

5- Code on demand (optional)

Servers can temporarily extend or customize the functionality of a client by the transfer of executable code. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript.
* this is the only optional constraint of the REST architecture.

6- Uniform interface

  • Identification of resources
    Individual resources are identified in requests, using URIs.
  • Manipulation of resources through these representations
    When a client holds a representation of a resource,it has enough information to modify or delete the resource.
  • Self-descriptive messages
    Each message includes enough information to describe how to process the message, using MIME types.
  • Hypermedia as the engine of application state (HATEOAS)
    Clients make state transitions only through actions that are dynamically identified within hypermedia by the server
     

" Talk is cheap, Show me the code "

-- Linus Torvalds

Discussing Github APIs

Base URL : https://api.github.com

Entities: Users, Repos,Gists ...

How to deal with those Entities ?

Create, Read, Update, Delete (CRUD)

POST, GET, PUT, DELETE

Map Operations to HTTP Verbs :-

- How to list all Users ?

POST /getAllUsers HTTP/1.1
Accept: */*
Host: api.github.com

BAD DESIGN !!!

URLs should contain (Plural) Nouns
Embrace HTTP Verbs

GET /users HTTP/1.1
Accept: */*
Host: api.github.com

- How to display user 'eslamx7' basic information?

GET /users?username=eslamx7 HTTP/1.1
Accept: */*
Host: api.github.com

Keep URL Simple !!!

Avoid using Query Strings as Entity Attributes

GET /users/eslamx7 HTTP/1.1
Accept: */*
Host: api.github.com

Much better,simple and more readable

- How to list public repos of user 'eslamx7' ?

GET /users/eslamx7/repos HTTP/1.1
Accept: */*
Host: api.github.com

Got it... ?

API Versioning

GET graph.facebook.com/v2.3/me HTTP/1.1

URL

GET eslamx.com/api/me HTTP/1.1
X-API-Version: 1.2

Custom request header

GET api.github.com/users/eslamx7 HTTP/1.1
Accept: application/vnd.github.com.v2+json

Accept header

GET api.eslamx.com/me?v=2 HTTP/1.1

Query String

Hints

Formats (JSON, XML)

Error Handling

HTTP Status Codes

Error Messages

Pagination

Offset / Limit

HATEOAS

Rate Limit

Securing Web API

  • Basic Authentication is bad
    if must, then you must use SSL
     
  • OAuth 2 (require SSL too)
     
  • HMAC (fine without SSL)

Resources

• Your API versioning is wrong, which is why I decided to do it 3 different wrong ways

• 5 Golden Rules for Great Web API Design

• Designing a Secure REST (Web) API without OAuth

• HMAC REST API Security

• Best Practices for Designing a Pragmatic RESTful API

Tools...?

Fiddler

HTTPie

Postman

Thank You :)

Questions ?

Follow me : @EslaMx7

RESTful Web API Design Guidelines

By Eslam Hamouda

Made with Slides.com

RESTful Web API Design Guidelines

introduction to REST-based web API, how to design a mobile-friendly web API, how to secure an API.

  • 1,942

More from Eslam Hamouda