RESTful API Design

What is an API? 

Application Programming Interface (API)

An API can be thought of as a contract provided by one piece of computer software to another.

This is an API

What makes an API RESTful? 

REST = Representational State Transfer

  Architectural Constraints

  • Client-Server

  • Stateless

  • Cacheable

  • Layered System

  • Code on demand (optional)

  • Uniform Interface 

Client-Server

Stateless

Cacheable

Layered System

Code on Demand (Optional)

Uniform Interface

  1. Resource Identifier
    • A URL identifies a resource.
    • http://example.com/api/v1/magazines/123/photos
  2. Resource Representation
    • HTML, JSON, XML, PNG, etc.
  3. Self-descriptive messages
  4. Hypermedia as the engine of application state (HATEOAS)

Why does this matter?

  • Performance
  • Scalability
  • Common Interface
  • Simplicity

APIs pretty much run the world.

Reuse, Good for Business

Can you name some APIs?

Example APIs

What kind of API resources do they provide?

Best Practices

  • Use HTTPS
  • Data Formats, JSON vs. XML
  • HTTP Protocol
  • CRUD <> GET, POST, PUT, DELETE, etc.

JSON vs. XML

JavaScript Object Notation

eXtensible Markup Language



{
    "person": {
        "firstName": "Hello",
        "lastName": "World",
        "phoneNumbers": {
            "mobile": 1234567890,
            "home": 987654321
        }
    }
}


<?xml version="1.0" encoding="UTF-8"?>
<person>
    <firstName>Hello</firstName>
    <lastName>World</lastName>
    <phoneNumbers>
        <mobile>1234567890</mobile>
        <home>987654321</home>
    </phoneNumbers>
</person>

HTTP (Hypertext Transfer Protocol)

  • HTTP Verbs  
    • (GET, POST, PUT, DELETE, PATCH*, etc.)
      • provides strategies to handle CRUD actions
  • HTTP Status Codes
    • 200, 201, 301, 404, 500, etc.
  • HTTP Header, Request
  • Uniform Resource Identifier

CRUD <> GET, POST, PUT, DELETE

CRUD HTTP Verb
Create POST
Read GET
Update PUT
Delete DELETE

Open Q&A

REST API Exercise

File Structure

Creating Our Database and Connecting

// server.js

// BASE SETUP
// =============================================================================

...

var mongoose   = require('mongoose');
mongoose.connect('mongodb://localhost:27011/'); // connect to local database

...

In a new command line window, start a local database:

Instead of the instructions, please use the following code snippet in server.js

mongod --dbpath=./db --port 27011

(You will have two terminals running, one for node and one for mongodb.)

End Result

You created your first RESTful API! Hooray!

Extra Credit: Can you combine what you learned today with last week's lesson?

Node.js, Express.js, MongoDB, Postman

Tools

  • Node.js was created to enable JavaScript to run on the server.
  • Express.js is a node framework for creating APIs
  • MongoDB is a NoSQL, document oriented database; using JSON-like documents rather than traditional relational databases
  • Postman is a browser plugin to interact with APIs

Install MongoDB

brew update
brew install mongodb

Install Homebrew

Quick Tip: Auto-refresh Node API


By default, node doesn’t automatically refresh our server every time we change files.

To do that we’ll use nodemon. 

npm install -g nodemon
nodemon server.js

Install:

Usage

Intro to RESTful API Design

By Kristian Tran

Intro to RESTful API Design

  • 1,151