Getting Started with REST APIs

Find the API Documentation

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Figure out authentication

• REST APIs have various methods of authenticating calls. To discover what kind of authentication a particular API uses, read the documentation for that API

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Determine the Endpoints

• An endpoint is the URI where you send an HTTP request

# Syntax
xyz://username:password@example.com:456/path/data?key=value#fragid1

# Examples
# <HTTP method> <endpoint>
GET https://mysite.com/api/customers

GET https://mysite.com/api/customers/1
# or
GET https://mysite.com/api/customers/details/1

PUT https://mysite.com/api/customers/1
# or
PUT https://mysite.com/api/customers/update/1

DELETE https://mysite.com/api/cutomers/1
# or
DELETE https://mysite.com/api/customers/delete/1

POST https://mysite.com/api/customers

• An API provider can make an endpoint URI private and accessible only through a VPN or can make it completely public on the Internet. API endpoints require https or TLS and are publicly available
• To improve performance, a provider might include the geographical location of an endpoint to specify an instance of the API. Amazon Web Services does this with the endpoint, https://dynamodb.us-west-2.amazonaws.com
• You can learn which endpoints are available by reading the documentation

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Understanding REST API Verbs

• Refer to previous section

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Understanding REST API parameters

• Parameters often provide details so that you can scope, filter, or clarify a request. These parameters are usually optional

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Understanding REST API Data Formats

• When sending a request, data formats are also called payloads. Refer to the REST API Documentation for your product to learn if it supports JSON and XML as data formats
• If you want to find out the format, check the documentation and then to verify, check the Content-Type header that's returned

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

REST API Tools

curl

• Stands for "Client for URLs"
• Linux command line application
• When using cURL to make REST API method calls, you typically use the following options and arguments:
◇ -X followed by a request verb such as GET, PUT, POST, PATCH, or DELETE
◇ -H followed by a header such as a token to send with the requests

# Examples: curl (with authentication)
curl -X GET https://api.ciscospark.com/v1/teams -H "Authorization:Bearer YjE2...e10f"

curl -H "Authorization:token OAUTH-TOKEN" https://api.github.com

curl https://api.github.com/?access_token=OAUTH_TOKEN

curl 'https://api.github.com/users/whatever?client_id=xxxx&client_secret=yyyy'

Postman

• A Chrome browser plugin or stand-alone application for API development environment
• You can generate Python code that uses the Requests library within Postman

Python Requests

• Requests is a Python library for automating tasks using a REST API
• Documentation and examples available at http://docs.python-requests.org/

OpenAPI / Swagger

• Dynamic API Documentation

Browser Developer Tools

• View traffic and details within the browser

Index