api_notes.md

This is notes for me to remember what to talk about in the workshop. Not really useful for others.

Web API's

A web server providing programmatic access to data and functions on the server. Your program sends a request to the server and acts like a web browser. The server sends a response back to your program.

Use this example: GBIF API

Hypertext Transfer Protocol (HTTP)

Discuss illustrations found here: https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview

Request methods and headers: https://developer.mozilla.org/en-US/docs/Glossary/Request_header

Response headers and status codes: https://developer.mozilla.org/en-US/docs/Glossary/Response_header

Using the GBIF API by hand:

Send a request:

nc api.gbif.org 80

Request:

GET /v1/species/5231190/vernacularNames HTTP/1.1
host: api.gbif.org
accept: application/json,text/html

This should give a response with a HTTP header and JSON payload.

What is JSON?

JavaScript Object Notation (JSON) is a lightweight data-interchange format. It contains either dictionaries (key-value pairs) or lists of dictionaries.

Example:

{
  "name": "John Doe",
  "age": 42,
  "children": [
    {
      "name": "Mille",
      "age": 10
    },
    {
      "name": "Mikkel",
      "age": 8
    }
  ]
}

Look at the response from the GBIF API.

The requests package

The requests package is a simple HTTP library for Python. It allows you to send HTTP requests and get responses. See documentation.

Making a request to gbif.org

Explain the code

Making a request to gbif.org using pygbif package

Explain the code

Using the Specify API

Explain the code

See also the tables API documentation and the operations API documentation.

We need the operations API to login and logout. The tables API allows us to interact with the Specify database.

WARNING: You can make serious damage to the Specify database if you are not careful.