Skip to content

API

What Why When

  • Do you need a web api?
    • Do you have clients that will call your service?
    • Do you have justification for creating and maintaining the api?
  • If you already know that you'll be building a web api, can use:
    • SOAP
    • REST
    • GraphQL
    • gRPC

HTTP protocol background

  • Client sends a Request to Server with the follow data:
    • Verb that describes what action to take
    • Headers give info about request
    • Content might be optional
    • eg: PW(Verb) ContentType JSON(Content) UM/PW(Content)
  • Server returns a Response with this data:
    • Status Code given info on success, failure, why failure
    • Headers give info about response
    • Content might be optional
    • eg: 200 (Status Code)
  • The Server is stateless as soon as it sends the response, it'll forgot about the request
    • This way, multiple servers can give responses and
      • be able to handle a lot of requests without storing state in memory waiting for another request
    • It's more about passing messages than getting a connection from a server

REST

  • REST - REpresentational State Transfer
    • not a standard, notation, language, protocol or specification
    • Made up by Roy Fielding's doctoral dissertation
    • An architectural style for designing apis in the hope that you're productive
      • with a generally agreed upon set of principles and constraints
  • "RESTful" apis means you're using REST (might not be 100% but you're trying)
    • Theory doesn't always consider reality so stay focused on the practical advantages of why you want to represent data this way
  • Concepts involve:
    • Use a Client and Server
    • Make sure Server Requests are stateless
    • Requests should support caheability
    • Requests should use Uniform Interface (URI)

Request Verbs

  • An indication of what you want to do on a specific request
  • GET: Read resource(s)
    • Wants to retrieve a or a collection of resources (eg: Site or sites)
  • POST: Create resource(s)
    • Adding/creating a new resource
    • For anything else that doesn't map clearly into the other verbs
  • PUT: Update resource
    • Updating/Modifying a resource by taking in information that might've changed (the whole object) and updating the existing resource to reflect the new data
  • PATCH: Update partial resource
    • Updating a resource with some data changes (partial object not not the whole resource)
  • DELETE: Delete Resource
  • OPTION:

Request/Response Headers

  • Essentially metadata about request
  • Can define your own headers are well but some common ones:
  • Content Type: The format of what the content section is holding such as json, xml, etc
  • Content Length: Gives info on how much (size) of content
  • Authorization: Who is making the call
  • Accept: Indicates what kind of data is acceptable when sending a response
  • Cookies: Data sent with request to help maintains state. Data can be sent back in response in subsequent calls
  • Expires: Response Header gives info on how long the browser might cache it

Request Content

  • Content is not sent with GET verb usually cause' you just wanna ask for something
  • HTML page that might have might have: HTML, CSS, JS, Binary files like jpg, blobs
  • APIS, XML, JSON
  • Could be basically anything that helps fulfill the request

Response Status Codes

  • For a huge list:
  • For a internet themed lis: https://http.cat/
  • 100-199: Informational
    • rare but exist
  • 200-299: Success
    • what you want was done successfully
    • 200 is most common
    • 200(OK) - The request completed successfully.
    • 201(Created) - The request has been fulfilled and resulted in a new resource being created successfully.
    • 202(Accepted) - The request has been accepted for processing, but the processing has not been completed.
  • 300-399: Redirection
    • not saying success or fail, just that it's in the wrong place
    • what you want was moved to somewhere else
    • if the data is cached already
  • 400-499: Client Errors
    • the way the client made the request is wrong
    • authentication issues
    • wrong query string in uri
    • uri doesn't exist
    • 400(Bad Request) - The request is invalid. Check error msg and try again
    • 401(Unauthorized) - The request requires authentication, or your authentication was invalid
    • 403(Forbidden) - You are authenticated, but do not have permission to access the resource (authorization verification)
    • 404(Not Found) - The resource does not exist
    • 429(Too Many requests) - You are being rate limited, try making fewer requests
  • 500-599: Server Errors
    • Server says: Its not you, it's me
    • 500(Server Error) - Service unavailable, try again later

Designing a RESTful API

  • Eg pubic Restful API: https://api.github.com/
  • Based on requirements, things to consider:
    • Figure out Boundaries such as:
      • Participants who are directly involved (user story)
      • Activities that the participants can do (breaking the user story into steps)
      • Go through happy path first, then edge/ambiguious cases
    • Identify the resources (nouns)
      • These are the nouns in the activities that the participants want to do.
      • Don't try to map your database entities into api resources unless it makes sense
      • For each noun, question if it's a separate item or just a collection of items
        • Question relationship between resources. Each resource can be:
          • Independent
            • Can exist on it's own without other resources. Eg: Cart
          • Dependent
            • One resource exists only if a dif resource exists. Eg: Orders from Carts
          • Associative
            • Need additional info to describe it and can be independent or dependant
      • These nouns will be mapped to HTTP verbs
    • Paths to Resources (URI)
      • Plural Nouns
        • Why: essentially giving an indication about what resource group is in this container that holders the info the the client might or might not want.
        • Resource groups can be one or more within the context of the app. Eg:
          • Why: Separating resource groups down to the entity level doesn't always make sense. Eg, Milestones don't exist on their own within projects.
          • Resource 1: Projects, Milestones within that project, Milestones with a discrete level of completion.
          • Resource 2: Proposals
      • Each resource will need an unique identifier to be able to drill in. Could be PK or any unique integer, string, UUID, username, etc
        • Will result in unique url for each resource (the Identifier in URI)
        • Why: Assuming client want to drill in, a descriptive path variable makes it easier to know what it is that you're getting info about instead of a random number.
        • Eg: https://api.github.com/users/prasunakunasani
          • Id here is the username while the PK is probably different within the app
      • Using /api path before resource to indicate the api
        • Eg:
        • Why: the assumption is that you have other site resources being served at /. If the app is just an api and nothing else, this might not matter

      • HTTP Verbs

        • Think of these like the use cases you want to let your user do. So, only support the verbs that make sense.
        • Eg: (kinda not sure the right way regarding updating in bulk...better to send 100 post request with their own status code or send a bulk one? or send bulk but return an array of status codes?)
        Request resource GET POST PUT Delete
        /-collection return list create single resource Update a single item or a collection Error - Try to think of a single use case
        where you want to delete an entire collection without filters.
        In prod.
        /-collection/{id} return just the item Error - Doesn't make sense to create a resource
        within a specific resource        		 Update the single item Delete the item
        /-collection/-collection return list create multiple sub-resource assume they relate
        (even if there's no entity in db)        		 Update a collection or a whole sub collection Error
        * Optional query strings for formatting, sorting, filtering
        * eg: nouns?page=1, nouns?sort=id
        * Shouldn't be mandatory
        * Why: Think about how annoying it is when you want to access some data and you're asked to first figure out how many pages you want to see, sorting,etc before you see anything.
        * Headers
        * Request Body
        * Things to considering when responding:
        * Status Code
        * Should reflect what the status codes usually mean. Eg, 201 if a resource is created
        * Headers
        * Response Body
        * Might send errors that are clearer to the user. Eg. when a mandatory field is empty or missing
        * Goal - Want some imperfect documentation before the API is developed for evaluation and validation. Including:
        * List of end points and what they do
        * List of parameters and what they mean
        * List of response codes and when you get each
        * Response payloads with fields
        ## Validating API
        * Lofi-Use white board and stickies with Verbs and work through User stories
        * Medfi - Use a API mock server
        * Hifi - Using a framework that allows you to build a API and a open api file

API Development+Documentation+Testing Tools

Curl

  • command line tool
  • Eg:
    • curl index.html gives the body of request
    • curl index.html -I gives headers+status code and but not the response body
    • curl index.html -i gives headers+status code and the response body

Postman

  • Desktop tool https://www.postman.com/
  • free tier available for team collaboration
  • can generate preview documentation for tested endpoints

Insomnia

Insomnia Designer

Postwoman /Hoppscotch

Other

Last update: October 13, 2020