Doc is  the interface

Architectural style requires users to consult docs

REST API growth

Services mashup

REST API model

REST characteristics

• REST == Representational State Transfer
• Named by Roy Fielding, modeled after web
• Nouns and verbs (resources and methods)
• Stateless
• Cacheable
• Uses web protocols

The web follows REST

Mashape API Directory

Activity

1. Go to market.mashape.com.
2. Find Weather by fyhao (market.mashape.com/fyhao/weather-13)

Compare with Aeris Weather API

Activity

Make a request to each weather endpoint using Postman.

Activity

On a command prompt, type and compare the following:

curl http://example.com -i

curl http://example.com -I

Unpacking the Mashape example

                  curl --get --include 'https://simple-weather.p.mashape.com/aqi?lat=37.3
54108&lng=-121.955236' \
-H 'X-Mashape-Key: {api key}' \
-H 'Accept: text/plain'
               

cURL commands

Full example

curl -i -H "Accept: application/json" -X POST -d "{status:MIA}"
   http://personsreport.com/status/person123
   

Activity

Use cURL to make the same weather requests you made in Postman.

JSON arrays are lists of items

["first", "second", "third"]

Objects can appear inside arrays

[
   {
      "name":"Tom",
      "age":39
   },
   {
      "name":"Shannon",
      "age":37
   }
]

Arrays can appear inside objects

{
"children": ["Avery","Callie","lucy","Molly"],
"hobbies": ["swimming","biking","drawing","horseplaying"]
} 

Activity

Identify the objects and arrays in the weatherdata endpoint response.

Logging the response to the console

Activity

1. Go to this sample page: idratherbewriting.com/files/restapicourse/weatherdata.html
2. Open the JavaScript Console (View > Developer > JavaScript Console).
3. Click Run the request
4. Investigate the JSON object logged to the console. Find the wind details.

Essential sections in API ref topics

• Endpoint description
• Request URL
• Methods
• Parameters
• Request example
• Response example
• Status and error codes
• Code samples

Some examples

• Mailchimp
• Twitter
• Instagram
• EventBrite
• Box

When it gets confusing to refer to resources by the endpoint

api_site.com/{apikey}/users
// gets all users

api_site.com/{apikey}/users/{userId}
// gets a specific user

api_site.com/{apikey}/rewards
// gets all rewards

api_site.com/{apikey}/rewards/{rewardId}
// gets a specific reward

api_site.com/{apikey}/users/{userId}/rewards
// gets all rewards for a specific user

api_site.com/{apikey}/users/{userId}/rewards/{rewardId}
// gets a specific reward for a specific user

api_site.com/{apikey}/users/{userId}/rewards/{missionId}
// gets the rewards for a specfic mission related to a specific user

api_site.com/{apikey}/missions/{missionid}/rewards
// gets the rewards available for a specific mission

Activity

Critique the Mashape Weather API descriptions.

Compare with Aeris Weather API descriptions.

Represent parameter values with curly braces

/campaigns/{campaign_id}/actions/send

The method

• Box API
• Linkedin

4 Types of Parameters

• Path parameters
• Header parameters
• Query parameters
• Request body parameters

Listing data types

• string
• integer
• boolean
• object

Query parameter order is irrelevant

/surfreport/{beachId}?days=3&units=metric&time=1400

 /surfreport/{beachId}?time=1400&units=metric&days=3

Parameters in the request body

{
"days": 2,
"units": "imperial",
"time": 1433524597
}

API Explorers provide interactivity with your own data

Strategies for nested objects

JS wizardry

Where to include sample responses

Auto-generating code samples

Essential sections

• Overview
• Getting started
• Authorization keys
• Code samples/tutorials
• Response and error codes
• Quick reference

Basic Auth

Authorization: Basic bG9sOnNlY3VyZQ==
               

HMAC

OAuth 2.0

Rate limits

Status codes specific to endpoints

Possible reasons for errors

• Invalid API keys
• Wrong data types
• Bad JSON syntax in post body
• No resource to return
• Rate limits exceeded
• Max or min values exceeded
• Missing parameter
• Network-related error

Activity

Look at about 5 different APIs from this list: idratherbewriting.com/pubapis_apilist. Identify one thing that the APIs have in common.

Activity

1. Create a Github wiki and publish content on a sample page.
2. Save the Github repository locally.
3. Make a change locally, commit it, and push the commit to the Github repository.

Activity

Using the Swagger Petstore (http://petstore.swagger.io/):

1. Create a new pet.
2. Find your new pet by the ID.
3. Delete your pet.

Sample syntax

reindeer:
  - Donner
  - Blitzen
  - Comet
  - Cupid
hobbies:
  active:
    - flying
    - prancing
  inactive:
    - pawing
    - driving

items:
  - title: Course overview
    url: /docapis_course_overview/
    weight: 1.0
    audience: writers

address: 1234 main street
route: Google maps
   

My YAML tutorial

Lucybot

Writing in Jekyll

Github Pages

Five patterns

• Structure and templates
• Website platform
• Abundant code samples
• Long-ish pages
• API Interactivity

Strategies

• Demonstrate technical aptitude with samples
• Build wide (not deep) knowledge of programming
• Participate in open source projects
• Create tech tutorials
• Create Swagger UI outputs for a company's docs