APIs

Interacting with 3rd party services to build custom applications!

What are they?

API: Application Programmable Interface

What are they?

Essentially a standard way to interact with a system
Usually via libraries / SDKs

System A

System B

System C

Read data from

System C via

System C's API

Send data to

System B via

System B's API

What are they?

Maybe you have a calendar app that lists all events on a calendar
- Read data from Google Calendar
And allow people to sign up to receive emails about the event
- Sign them up to receive email updates

Your App

Mail Chimp

Google Calendar

Read events in Google Calendar and display them in your app

Send register user details to Mailchimp to receive

mail outs

Why use them?

Similar to webhooks
- Allow you to use existing (and hopefully powerful) systems without having to build your own
Building customized functionality
- Especially that fits into particular workflows to easy adoption

What do they look like?

$ curl https://api.intercom.io/users \
-X POST \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
  "user_id": "25",
  "email": "wash@serenity.io",
  "name": "Hoban Washburne"
}'

import io.intercom.api.User;
import io.intercom.api.Intercom;

Intercom.setToken(MY_TOKEN);
User user = new User()
    .setEmail("wash@serenity.io")
    .setUserId("25")
    .setName("Hoban Washburne");
User created = User.create(user);

require 'intercom'
intercom = Intercom::Client.new(token: MY_TOKEN)
user = intercom.users.create(email: "wash@serenity.io", 
  name: "Hoban Washburne", user_id: "25")

Your App

System B

Send data

Receive response

$ curl https://api.intercom.io/users \
-X POST \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
  "user_id": "25",
  "email": "wash@serenity.io",
  "name": "Hoban Washburne"
}'

The breakdown of a request

Authorization / Authentication
Format the client Accepts
Format the client is sending
Data

Things can be optional!

Authorization / Authentication

$ curl https://api.intercom.io/users \
-X POST \
-H 'Authorization:Bearer <Your access token>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
  "user_id": "25",
  "email": "wash@serenity.io",
  "name": "Hoban Washburne"
}'

API Key / Access Token

Simple
Usually for accessing your own data
(best used for internal tools)
Has a single kind of permission level

Authorization / Authentication

https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2

OAuth

Best for reading user data e.g. your app provides a service to people and allows them to give your app access to their resources. E.g. social media tool
Individual tokens for each person

Authorization / Authentication

https://developers.facebook.com/docs/facebook-login/permissions/overview/

OAuth

More varied permissions
Ability to allow / deny specific permissions
More complicated

Authorization / Authentication

OAuth

https://developers.google.com/calendar/quickstart/ruby

Authorization / Authentication

OAuth

https://developers.google.com/api-client-library/ruby/auth/web-app

On to the code!

I'm on the different version and I don't want to break existing projects
Versions managers to the rescue!
Use different versions without messing up your existing installations
- php-version
- rbenv
- rvm
- nvm
- pyenv
IDEs