Kai 2-API-Basics.pdf

JSON = JavaScript Opject Notation

• Language-independent data format for data interchange
• Subset of JavaScript
• Good documentation: http://json.org
• ECMA Standard

JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data.

<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