Kai 2-API-Basics.pdf

<value> ::= true | flase
                   <number> |
                   <string> |
                   <array> |
                   <object>

Number:

• Decimal, possibly signed
• Both integer or floating point
• May use exponential E notation
• Example: 3.22

Array:

• Orderd list of values
• Possibley empty
• Example: [123, "abc", 324.23]

String:

• A sequence of unicode characters
• Delimited by: "
• Escaped by: \
• Example: "This is a: \t string"

Object:

• Unorderd list of key/value pairs
• Possibly empty
• Keys are strings
• Example: {"key1": 123, "key2": "blah"}

• Whitespace outside of strings are ignored some examples:
  • tabs
  • spaces
  • line feed
  • carriage return
• There are no comments
• Object keys are case sensitive
• JSON is only encoded in UTF-8 (default), UTF-16 or UTF-32
  • There is no deed to specify the encoding,
    it can be determinded from the first two bytes

REST = REpresentational State Transfer

• Servers expose resources using a URI
• Server store no state about client (no session)
• Client transfers its state with each request

REST (REpresentational State Transfer) is a sofware architectural style that defines a set of constraints to be used for creating Web services. Web services that conform to the REST architectural style are called RESTful Web services (RWS). they provide interoperability between computer systems on the internet.

Clients access REST resources using the four HTTP verbs:

• DELETE
• GET
• POST (create)
• PUT (update)

• 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)