p3-insta485-clientside

REST API Tools

This tutorial shows how to use command line tools to interact with a REST API.

Install

Make sure you have curl and HTTPie installed.

Linux and Windows 10 Subsystem for Linux

$ sudo apt-get install curl httpie

MacOS

$ brew install curl httpie coreutils

Sanity check

Your versions might be different.

$ curl --version
curl 7.54.0 (x86_64-apple-darwin16.0) libcurl/7.54.0 SecureTransport zlib/1.2.8
$ http --version
1.0.3

Basic usage

A REST API sends JSON data over HTTP. First, try it in your browser. For this example, we’ll use the GitHub REST API. Navigate to https://api.github.com/users/awdeorio. You should see something like:

{
  "login": "awdeorio",
  "name": "Andrew DeOrio",
  "public_repos": 5,
  ...
}

Using curl, we can do the same thing at the command line.

$ curl https://api.github.com/users/awdeorio
{
  "login": "awdeorio",
  "name": "Andrew DeOrio",
  "public_repos": 5,
  ...
}

Better yet, HTTPie (the http command) provides color-coded results. It also makes complex requests easier to type. This is the recommended utility.

$ http https://api.github.com/users/awdeorio
HTTP/1.1 200 OK
...
{
  "login": "awdeorio",
  "name": "Andrew DeOrio",
  "public_repos": 5,
  ...
}

REST APIs and sessions

Some REST APIs require a login, for example, EECS 485 Project 3. These examples show how to use sessions with HTTPie.

To try these examples, start your EECS 485 Project 3 development server.

$ ./bin/insta485run

Request to the REST API without a login results in a 403 error. Note: this assumes a complete project 3 implementation.

$ http "http://localhost:8000/api/v1/p/1/likes/"
HTTP/1.0 403 FORBIDDEN
...

Login using HTTPie to fill out the login form. This will save a file called session.json containing a cookie set by the server.

$ http \
  --session=./session.json \
  --form POST \
  "http://localhost:8000/accounts/login/" \
  username=awdeorio \
  password=password \
  submit=login
HTTP/1.0 302 FOUND
...
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>Redirecting...</title>
...

HTTPie will use the cookie in session.json to authenticate to the insta485 API.

$ http \
  --session=./session.json \
  "http://localhost:8000/api/v1/p/1/likes/"
HTTP/1.0 200 OK
...
{
    "likes_count": 3,
    "logname_likes_this": 1,
    "postid": 1,
    "url": "/api/v1/p/1/likes/"
}

Pro-tip: shell script shortcuts

Save some typing by writing a short script that logs in and make a request. Here is shell script code for a sample resttest.sh.

#!/bin/bash
set -Eeuo pipefail
set -x

# Log in
http \
  --session=./session.json \
  --form POST \
  "http://localhost:8000/accounts/login/" \
  username=awdeorio \
  password=password \
  submit=login

# REST API request
http \
  --session=./session.json \
  "http://localhost:8000/api/v1/p/1/likes/"

Don’t forget to make the script executable.

$ chmod +x resttest.sh

Run.

$ ./resttest.sh
+ http --session=./session.json --form POST http://localhost:8000/accounts/login/ username=awdeorio password=password submit=login
HTTP/1.0 302 FOUND
...

+ http --session=./session.json http://localhost:8000/api/v1/p/1/likes/
HTTP/1.0 200 OK
...

{
    "likes_count": 3,
    "logname_likes_this": 1,
    "postid": 1,
    "url": "/api/v1/p/1/likes/"
}

POST requests

We can also make POST requests with HTTPie. Note that HTTPie implicitly uses JSON as the content type for all requests so we don’t need to specify the content-type in the POST header:

$ http \
  --session=./session.json \
  POST \
  "http://localhost:8000/api/v1/p/3/comments/" \
  text='Comment sent from httpie'

Update .gitigore

Be sure to add session.json and cookies.txt to your .gitignore. These files shouldn’t be in version control.