REST APIs

REST APIs

1. Example

   • Star Wars API (SWAPI)
     • URL
       • https://swapi.dev/
     • Data Interface
       • Usability Principles
         • Learnability, utility, accessibility, effectiveness and safety
       • Elements of Design
         • Space, line, colour, shape, texture, tone, form, proportion and scale
       • Principles of Design
         • Balance, contrast, proximity, harmony, alignment, repetition and heirarchy
       • Raw JSON output
         • <pre>{{result}}</pre>
           • <pre> tag preserves style of JSON text
     • Data Structure
       • JSON
         • Curly braces around objects
           • {}
         • Key and value pairs
           • Separated by colons
             • :
         • Square brackets around arrays
           • []
         • Quotes enclosing character data elements
           • ""
         • Commas separating pieces of data
           • ,
         • Heirarchical
           • URI values
     • Data Specifications
       • Data Structure
         • JSON Schema
       • Data Definition
         • URI
           • URL
             • https://swapi.dev/api/
           • URN
             • people/1/
             • Data categorised in six resources
               • Planets, Spaceships, Vehicles, People, Films and Species
               • Each record in a category has a unique number
       • Dataset Name
         • SWAPI
       • Data Validation
         • None
       • Data Security
         • Rate limiting
           • Done via IP address
           • 10000 API requests per day
         • Authentication
           • None
         • Encoding
           • JSON
           • Wookiee

2. REST Principles

   • Uniform Interface
     • Information is transferred in a standard form.
       • Requested resources identifiable and separate from the representations sent to the client.
       • Request
         • Endpoints
           • The URL/URI where the API/service can be accessed by a client application
             • https://mysite.com/api/users
               • GET, POST
             • https://mysite.com/api/users/[http method]/1
               • GET, PUT, DELETE
             • https://mysite.com/api/users/1
               • GET, PUT, DELETE
             • The same URI/URL can be used with different methods
         • HTTP Methods
           • OPTIONS
             • Returns the supported HTTP methods
           • HEAD
             • Same as GET, but does not return a body.
           • PATCH
             • Update partial resources
           • DELETE
             • Deletes a specified resource
           • GET
             • URI also used to get HTML webpages
             • Retrieve data from a specified resource
           • POST
             • Submit data to be processed to a specified resource
             • Also used by HTML forms
           • PUT
             • Update a specified resource
             • Only works with code
       • Response
         • Codes
           • 200s
             • Success
           • 400s
             • Input error
           • 500s
             • Server error
         • Data
           • JSON
           • XML
           • HTML
   • Stateless
     • No client information is stored between get requests and each request is separate and unconnected.
       • Specify pagination in URI
       • Authenticate using URI
   • Cacheable
     • Streamlines client-server interactions.
       • An HTTP response stored to be retrieved and used later, saving a new request to the server.
   • Client-server
     • Architecture made up of clients, servers, and resources, with requests managed through HTTP.
       • Rate limits
       • Authentication
         • API keys
         • Require a token to use the API service.
           • Can be free or paid.
           • -H "Authorisation: token OAUTH-TOKEN" https://api.mysite.com
             • Sending token inside of HTTP header
           • https://api.mysite.com/? access_token=OAUTH-TOKEN
             • Sending token as parameter in URI
           • Send token with requests
           • 'https://api.mysite.com/users/whatever ?client_id=xxxx&client_secret=yyyy'
             • Sending a generated client ID and secret as a parameter to the request instead of a token
         • Basic
   • Layered
     • Each type of server involved in retrieval organised into hierarchies.
       • Can include URIS to other APIs
   • Code-on-demand
     • Sending executable code to the client when requested.
       • Not Applicable

3. Definitions

   • REST
     • Representational State Transfer
       • Architecture Style
       • Treats server objects as resources that can be created or destroyed.
       • Can be used by virtually any programming language.
       • Relies on a stateless, client-server protocol.
   • API
     • Analogy
       • Restaurant
         • Kitchen is the server
         • Customers are clients
         • Waiter is the API
     • Application Program Interface
       • Contract provided by one piece of software to another
       • Structured request and response

Images and files in the map