API Design

tags : Distributed Systems, Systems, Web Development, Design Patterns, Authentication, HTTP, Security

FAQ §

Protecting API §

This comes down to a data question

If data is personal §

• Implement some sort of authentication and authorization

• In a browser log-in scenario

  

If the data is public §

• Run on the assumption someone will find a way to extract it.
• CORS will help, no?
  • CORS is not a rate limiting mechanism, it’s a way to get around browser limitations.
  • Doesn’t matter what CORS configuration you set on the API endpoint, it’ll always be fully accessible from a non-browser thing. (eg. curl)
• Consider API gateways
  • Track the usage pattern of requests
  • Rate limit to a point where automated data extraction is too slow.

API Endpoint security §

See IAM (Identity and Access Management)

Tokens §

• An authorization token is just a string that is used to authorize a request.
• It can be
  • A JWT (so-called pass-by-value tokens)
  • A random identifier (so-called pass-by-reference tokens)
  • Something else
• In the wild they call it, API keys, Personal access tokens etc.
• These are not necessarily outcome of the OAuth (Open Authorization) Flow.

OAuth and Protecting APIs §

See IAM (Identity and Access Management)

Exposing API §

• See Rate Limiting and Load Balancers
• API gateways like Kong
  • See Deploying Kong to AWS Elastic Container Service with Terraform
• Custom service

Native APIs §

• One can use session tokens to access native APIs.

REST / RESTful / REpresentational State Transfer §

Basics §

• REST APIs must be hypertext-driven
• Came from Chapter 5 of Fielding’s PhD Dissertation.
  • REST described a network architecture, and it was defined in terms of constraints on an API
  • It’s original meaning was opposite of RPC
• “If the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API.”

What it’s not §

• JSON-based API using HTTP. This is not a REST API.
• HTTP-based interface are NOT necessarily REST API. It is RPC (See Custom Protocols)

Constraint §

• Uniform interface constraint

  • The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server could send data from its database as HTML, XML or as JSON—none of which are the server’s internal representation.

• Hypertext

  • For REST to be true, hypertext is a constraint.

• Hypermedia (HATEOS)

  

  • See htmx - HATEOAS
  • A REST client should then be able to use server-provided links dynamically to discover all the available resources it needs. As access proceeds, the server responds with text that includes hyperlinks to other resources that are currently available.
  • The HTML response “carries along” all the API information necessary to continue interacting with the system directly within itself. Which is not the case with the JSON response, the client has to interpret the information of the JSON response and do certain logic based on it. i.e the response from the server is not sufficient to be delivered to the end user, which in the case of the HTML response, it is.
  • So, in a RESTful system, you should be able to enter the system through a single URL and, from that point on, all navigation and actions taken within the system should be entirely provided through self-describing hypermedia: through links and forms in HTML, for example.
  • The JSON style API response infact, is NOT RESTful! It’s more of a RPC style API, which requires the client to have additional knowledge.
  • HATEOAS isn’t a good fit for most modern use cases for APIs. , so it’s not like it’s only good if it is HATEOS, it’s just probably not REST. That’s it.
  • See Web Development

Why the industry calls non-RESTful APIs RESTful then? §

• See How Did REST Come To Mean The Opposite of REST?

Timeline (Early 2000s) §

• Roy Fielding published his dissertation on REST
• XML-RPC came out, RPC protocol, uses XML to encode data and uses HTTP as transport
  • Was part of Microsoft’s SOAP
• AJAX came out, browsers can now make HTTP requests in background.
  • What should these requests look like? since XML-RPC was around, let’s adopt it.
  • SOAP/XML-RPC was born
• This was being used for Web and humans, but people started exploring this for web services aswell, as an API.
• JSON came along, Javascript alternative to SOAP/XML-RPC
  • REST by itself was never tied to any tech such as JSON / XML-RPC
  • So people started switching to JSON and tried REST w it, but most stopped at L2 of the RMM !

RESTful became a spectrum than a concrete thing §

• Richardson Maturity Model (RMM)

Implementation of REST §

“Despite these difficulties, the term REST stuck: REST was the opposite of SOAP, JSON APIs weren’t SOAP, therefore JSON APIs were REST.” - grug

“battle was lost a long time ago. REST is just the common term people use for HTTP+JSON RPC.” - voidfunc

^This sentence summarizes the industry confusion

• Now as we know REST was been implemented by anything really but popular use include, HTML, JSON and XML-RPC
• JSON
  • Is obviously not a hypertext.
  • You can impose hypermedia controls on top of it, but it isn’t natural.
  • So usually, JSON API never truly actieve RESTful APIs in general
  • Eventually most people got tired of trying to add hypermedia controls to JSON APIs and gave up on it.
• XML
  • At least looked like HTML, kinda.
  • So it was plausible that you could create a hypermedia with it.
• GraphQL
  • GraphQL isn’t REST, it doesn’t claim to be REST, it doesn’t want to be REST