Kai 2-API-Basics.pdf

• Use self-explanatory nouns in your URLs
• Choose a URI for each resource you wish to expose
• GET should not change any data
• PUT and DELETE should be idempotent (multiple executions have the same result as a singe execution)
• Use links in your responses
• Use the HTTP Accept request header to chose representation (XML, JSON, ...)
• Use the Cache-Control response header ot control chaching
  • GET responses are cached by default,
  • POST/PUT responses are not
  • Set cahce-control: private to signal that data is specific to current user
• Use the Content-Type response header to specify the representation
• Use appropriate HTTP error codes

• 200 OK: Request was successful
• 201 Created: Request was successful and resource was created (PUT or POST)
• 400 Bad Request: Request was malformed. (PUT or POST request in the wrong format)
• 404: Not Found: Resource for that URL could not be found
• 401: Unauthorized: Authentication failed
• 403: Forbidden: Insufficent rights
  • GitHub returns 404 when you try to access someone else's (existing) user account -> no information disclosure
• 405: Method Not Allowed
• 500: Internal Server Error: failed to fulfill an apparently valid request

• Easiiest way to send username and password to a server
• Standardized by the IETF in RFC2617
• Process:
  1. Concatenate username and password like this: "john:password"
  2. Base64encode
  3. Put thes string after "Basic " in the Authorization header:
            Authorization: Basic am9wehEJSHJL==
• Password is transmitted in cleartext needs TLS
• The browser sends this only after gettin g a response with status 401 Unauthorized with a challenge like this:
  • WWW-Authenticate: Basic realm="Wallys World"
• For API access credentials are of course usually sent preemptively

Access Tokens:

• Most APIs that use HTTP Basic Authentication use server-generated access tokens instead of username/password
• They are often called API Keys or API Access Tokens, such as on GitHub

Benefits of access tokens vs. usrename/password

• Higher entropy: harder to guess
• Can create separate access tokens for separate applications
• Revoke-able
• Scope-able

1. Client: opens connection to server
2. Server: presents client its certificate
3. Client: Verifies certificate using local truststore
4. Client: sends request to server

SSL Client Authentication 

Also known as:

• Mutual SSL
• SSL with Mutual Authentication
• Two-Way SSL
• SSL with Client-Certificate

• Rarely used for communication with end-users
• Very much used for internal and B2B communication

1. Client: opens connection to server
2. Server: Presents client the server certificate
3. Client: verifies server cert. in local truststore
4. Client: presents server the client cert.
5. Server: verifies client cert. in local truststore
6. Client: Sends encrypted request to server

1. Client to Server: "client hello"
2. Server to Client: "server hello" + CipherSuite (what versions and protocols the server suportes)
                                                    + Server certificate
                                                    + "client certificate request" (opitonal)
3. Client: Verifies server certificate + Check cryptographic parameters
4. Client to Server: Sends secret key information (encrypted with server public key)
5. Client to Server: (if requested by server) Sends client certificate
6. Server: (if client cert. requested) Verifies the client cert.
7. Client to Server: Client "finished"
8. Server to Client: Server "finished"
9. Bi-directional: Exchange messages (encrypted with shared secret key)