Webbramverk, 1DV450
Linnéuniversitetet, vt 2016

RESTful Webb-API part 2

  Denna presentation är licensierat under en Creative Commons Erkännande 3.0 Unported Licens. (Där inte annat anges)

Response och statuskoder

# I controllern som genererar response

# respond_with rederar ut json/xml
# serializerar objektet @error (Error är en egen klass)
# I rails finns massor med fördefinerade statuskoder
respond_with  @error, status: :not_found
			

Versioning

Precis som all mjukvara kommer ditt API behöva uppdateras

Bakåtkompabilitet viktigt. Ge användarna en chans att ställa om. Vi måste kunna hantera versioner! Uppdatera sällan!

GET http:⁄⁄www.api.example.com/v1/products
GET http:⁄⁄www.api.example.com/v2/products
			

# No fun hacking in browser
Accept: application/vnd.coursepress-data+json;version=2.0
Accept: application/vnd.github.v3+json
			

http://stackoverflow.com/questions/389169/best-practices-for-api-versioning URL:er bör hållas kontakta så lnge som möjligt

Partial response (filtrering) & Pagination

⁄users⁄thajo:(firstname,lastname,email)
⁄users⁄thajo?fields=firstname,lastname,email

I http-protokollet finns Content-Range men...

⁄users?page=3&rrp=25
⁄users?start=100&count=25
⁄users?offset=100&limit=25

{
  "prev": "http://localhost/api/v1/users/?offset=0&limit=25",
  "next": "http://localhost/api/v1/users/?offset=50&limit=25"
}

API-keys

• Används främst för att kontrollera anropen (antal anrop, statistik)
• Gäller under lång tid! Ej vettigt för aktorisering!
• API nycklar kan lätt snappas upp, Vanskligt för aktorisering
• API-nycklar hör till utvecklaren/applikationen, inte slutanvändarna
• Spårbarhet, en nyckel per applikation
• Varje request kräver en nyckel...databasanrop? In-memory?

Rate limit

Begränsa antalet anrop till ditt API.
Headers som börjar med X har använts som custom headers Skickas med i respons från servern

• X-Rate-Limit-Limit - Antalet anrop inom en tidsperiod
• X-Rate-Limit-Remaining - Antal kvarstående anrop
• X-Rate-Limit-Reset - Antal sekunder kvar tills nästa "nollställning"

429 Too Many Requests

"Web hooks"

Låt användaren av ditt API registrera sig för ett event.
Server-to-server

Säkerhet

Authentication (Autentisering) - Fastställande av identitet

Authorization (Auktorisering) - Vilka resurser ska en identitet ha tillgång till

REST är stateless - ALL information i varje request

HTTP Basic authentication

# server HTTP Header
401 Unauthorized HTTP/1.1
WWW-Authenticate: Basic realm="my api"

# client HTTP header (base64-encodat username/password - ej krypterat)
Authorization: Basic Kl52osuDS3DH6H12JDe543

MÅSTE ANVÄNDA HTTPS! Ej krypterat!
username/password i varje anrop

Enkelt! Stöd i de flesta tekniker!

http://railscasts.com/episodes/352-securing-an-api

Username/password vs. Token-based

Har ett visst tidsspann

# beware of history, logging and proxies, unsafe- vs. safe methods
GET https:⁄⁄api.example.com/resource/?token=aksaj9dksjfKJLKSh2

JSON Web Token (jwt)

• Ett "standardiserat" sätt använda en mer avancerad token
• Skickas med varje request (i Authorization header), Stateless på servern
• Header, Payload, SECRET
• Enkelt bygga in tidskontroll
• Single sign-on
• JSON!

http://jwt.io/

There is a gem for that: https://github.com/jwt/ruby-jwt

Varför OAuth?

• Vill undvika att tredjeparts-applikationer (dina API-consumers) hanterar användarnas lösenord
• Dina API-klienter vill slippa hantera dina användare
• Man vill ge resursägare/slutanvändare möjlighet att begränsa åtkomsten till resurser
• Som resursägare/slutanvändare kan jag återkalla en tredjepartsapplikations rättigheter

Ska jag implementera en OAuth service?

Har din tjänst "resource owners"?

Kommer många användare av ditt API bygga klienter där de vill komma åt data som hör till en "resource owners"?

Krångligt?

• https://github.com/applicake/doorkeeper
• https://github.com/intridea/omniauth/