API Strategy

API Design, Service Platform, API Economy

API Design

First step, needs to have a stable good maintainable API

Service Platform

Once design is covered, that's when it becomes a platform and can be used throughout the organization

API Economy

Is when an economic opportunity becomes available, allowing the business to offer services in exchange to data access or price fee !ss_api_strategy.png

API Design (Principles/Foundations of REST)

From Roy Thomas Fielding, who coined the HTTP design !ss_principles_rest.png

Levels of API

Level 0: Swamp of POX (Single URI, Sinhle HTTP method, potentially using SOAP)
- Example:
  - /getAllEmployees
  - /getEmployeeWithId?id=1
Level 1: Resources - different URIs, doesn't take command of HTTP verbs
Level 2: HTTP verbs - good URIs + http verbs: GET, POST, DELETE, PUT
Level 3: Hypermedia - HATEOAS, Content Negotiation.

Content Negotiation - allows you to specify for example what the content-type you want, ie: xml vs json and the api can handle such request. Another example is GraphQL

HTTP verbs:

Common Verb usages:

Usage	Verb	Description	Idempotency	Safe
Listing	GET	Query a resource or collection	Yes	Yes
Creating	POST	Insert a single resource or perform a controller operation	No	No
Replacing	PUT	replace an entire resource	Yes	No
Updating	PATCH	Update 1 or many fields of a resource	No	No
Deleting	DELETE	Delete a single resource	Yes	No

Safe methods are HTTP methods that do not modify the resource

Starting Point on Designing APIs

Have a matrix on Who + What + How (inputs + Outputs) = Goals

Who	What	How	Input	Output	Goals
Customer	Buy Product	Search Product	Catalog, Free Query	Product	Search Product in Catalog using free query
		Add Product to Cart	Product, Cart		Adding Product to Cart
Admin	Manage Catagog	Add product to Catalog	Catalog, Product		Add product to Catalog

Error Codes

Generally using HTTP standard codes is good practice
Good format:

    "error": {
        "id": UUID,
        "code": 401,
        "message": "Request had invalid credentials.",
        "status": "UNAUTHENTICATED",
        "details": \[{
            "@type": "type.googleapis.com/google.rpc.RetryInfo",
        ...
    }\]
    }
}

Generally should contain:
- ID - for tracing purposes
- Code HTTP Code
- Status
- Title
- Link - to documentation for troubleshooting
- Details

URI Design

Use uuid as path params rather than id
Use URL encode
Query params are using used to extend the api for example pagination, searching, filtering

Cheat sheet:

Domain	Example
Collection	`/products`
Pagination	`?start=10&row=10`
Document	`/products/8d8d123a-ba34-4c42-8f35-3c0169f3972f`
Search/Filtering	`/products?q=description:consigned` or `/search?q=consigned`
Relations	`/products/8d8d123a-ba34-4c42-8f35-3c0169f3972f/reviews`
Partial Content	`/products?q=description:analgesic&field=id,name`
HTTP verbs	GET PUT PATH POST DELETE
Content	JSON XML
Versioning	`/v2/products`

Authentication

Basic Auth - User and Password
OAuth 2.0 - Access Token
Mutual Authentication - Assymetric certificates. 2 way SSL
Open ID - Federated access Token (Facebook, Google, Social media tokens)

Typical Flow OAuth 2.0 flow

!ss_oauth2_flow.png

Tokens

Opaque vs Transparent | Opaque | Transparent| | --- | --- | | Stateful | Stateless| | Meaningless content, it needs an Auth Server to validate if its valid | Meaningful content, Resource can decrypt it to get value| | Can check validate/introspect if revoked etc | No central service to validate/invalidate. Self validation | | Example Technology: APIGEE | JWT |

Typical JWT Flow

!ss_stateless_token.png

Should API have a different version?

If you dont control every client using the API
Change in the contract or removing critical portion of the API
Consider extending existing API, add new endpoints, add query params.
Remember to retire old APIs that are no longer used

API versioning strategies (knot, point to point, and compatible)

!ss_api_versioning_strategy.png

Pagination

Page-Based :

limit=20&page=1

Pros
- easy to implement, SQL backed
- Stateless
- works regardless of sort_by
Cons:
- Not performant on offset values, as Database still queries the first set and throws it away, 100000 would be really slow

Example Query: ORDER BY column_list [ASC |DESC] OFFSET offset_row_count {ROW | ROWS} FETCH {FIRST | NEXT} fetch_row_count {ROW | ROWS} ONLY

Keyset-Based:

limit=20&since_id=20
The sort_by needs to be consistent, i.e i can query where id >20 so it will always be consistent
Pros
- works with existing filters only need additional URL param
- New records inserted on previous pages will update accordingly
- Consistent performance
Cons
- Tight Coupling on paging mechanism on Sorting
- Does not work with string fields or enums (low cardinality fields: boolean, string as how do you sort by string)
- Complicated for API users when using custom sort_by

Example Query:

SELECT * FROM t AS OF SYSTEM TIME ${time}
  WHERE key > ${value}
  ORDER BY key
  LIMIT ${amount}

Cursor-Based

Response contains the following: if we had requested: ?limit=20 the response would include:

{
    results:[],
    users:21
}

in the intial query, we return the last value of the original response as the next_cursor:

SELECT * FROM users
ORDER BY id DESC
LIMIT %limit+1

we do not include the data from limit+1 in the response but only to keep track of the next cursor, on the subsequent call:

SELECT * FROM users
AND id <= %cursor
ORDER BY id DESC
LIMIT %limit

Another way to implement cursor is have a hash of the next cursor as an identifier.

For example you had a list of names: ║ Bagshot ║ Bathilda ║
║ Black ║ Sirius ║
║ Brown ║ Lavender ║
║ Chang ║ Cho ║
║ Creevey ║ Colin ║
║ Crouch ║ Bartemius ║
║ Delacour ║ Fleur ║
║ Diggle ║ Dedalus ║
║ Diggory ║ Cedric ║
║ Dumbledore ║ Aberforth ║
║ Dumbledore ║ Albus ║
║ Dursley ║ Dudley ║
║ Dursley ║ Petunia ║
║ Dursley ║ Vernon ║
║ Filch ║ Argus ║
║ Finnigan ║ Seamus ║
║ Fletcher ║ Mundungus

you can have the cursor as:

    “cursor”: {
        “previous_page”: null,
        “next_page”: "next___Creevey"
    }
}{
    “cursor”: {
        “previous_page”: "prev___Crouch" ,
        “next_page”: "next___Dumbledore"
    }
}

your query then says get all the names next to Creevey. gives you more flexibility with the sorts rather than the keyset pagination.

Pros
- More flexibility on filter logic
- Consistent ordering
- Consistent performance
Cons
- Potentially more complex to implement

H-Factor

Things to consider on Level 3 APIs (HATEOAS)
- LE - Embed Links
- LO - Outbound Links
- LT - Templated Links
- LI - Idempotent Links
- LN - Non-idempotent links
- CR - Read Controls
- CU - Update Controls
- CM - Method COntrols
- CL - Link annotations

API Gateway patterns

!ss_api_gateway.png

API Different Aspects

Concepts
Readability
Error Handling
URI Design
Authentication
Versioning
Data Handling

API Scaling

Further Reading: https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-1-ae3557c187e2

API Strategy

API Design​

Service Platform​

API Economy​

API Design (Principles/Foundations of REST)​

Levels of API​

HTTP verbs:​

Starting Point on Designing APIs​