API training

[jiaqing-tee]

API Training

Playlist: https://www.youtube.com/playlist?list=PLLTou95Km32Q_4mlqahPCD6eIWMPfQ-bi

[jiaqing-tee]

REpresentational State Transfer (REST) API

Title: What is a REST API? Link: https://youtu.be/lsMQRaeKNDk

Takeaway

• All about communication
• Restful web service: Service that use REST APIs to communicate

Benefits

• Simple and standardized approach to communication
• Scalable and stateless
• High performance: support caching

Request

• Create, Read, Update, Delete (CRUD)
  • Create: POST HTTP method
  • Read: GET HTTP method
  • Update: PUT HTTP method
  • Delete: DELETE HTTP method
• Items in Request
  • Headers: Can contain API key / authentication data
  • Operation: HTTP method
  • Endpoint: URL
  • Parameter / Body: Data sent over the request

Response

• Usually in JSON format

[jiaqing-tee]

Designing API

Title: What is an API and how do you design it? 🗒️✅ Link: https://youtu.be/_YlYuNMTCc8

Takeaway

• API is a documented way which external consumers can understand how to interact to get their work done

Best Practices

• Decide where should the function be exposed, under which service
• Naming: Should correspond to what the API do
• Parameters definition: Don't take additional parameters unless necessary
• Response object definition: Should only provide necessary data stated in the API
• Error definition: Don't take responsibility for edge cases, only provide expected error
  • Consider common expectations and responsibilities the API has
• HTTP Endpoints
  • Decide where API is going to be
• Side effects
  • For setting admin, might have such issues
    • Admin not an user in the group: Might need to add member then make them admin
    • Group does not exist: Create the group then make them admin
    • In such cases, we are doing more than just setting admins
  • API should not have such side effects
  • Need atomicity
• Pagination
  • Break response into pieces by
    • Pagination: Give responsibility to user
    • Fragmentation: Break the response down with TCP number
• Data Consistency
  • Read admins while someone added a new admin
  • Data was cache (old data)

[jiaqing-tee]

API Paradigms: Request Response Type

Title: REST vs RPC vs GraphQL API - How do I pick the right API paradigm? Link: https://youtu.be/hkXzsB8D_mo

Takeaways

2 types of APIs

1. Event driven APIs
2. Request response APIs
   • Representational State Transfer (REST)
   • Remote Procedure Call (RPC)
   • GraphQL

REST APIs

• Best for APIs that expose CRUD like operation
• Focus on resources, named with nouns like users
• Do not use verbs like getUsers
• Non-CRUD operations
  • Archive
  • Deactivate
  • Search
• Advantages
  • Standard method names, arguments, and status codes
  • Utilizes HTTP features
  • Easy to maintain
• Disadvantages
  • Big Payloads
  • Multiple HTTP roundtrips: Get resource then get subresources

RPC APIs

• Best for APIs exposing several actions
• Focus on actions, action usually part of URL
• GET for read-only requests and POST for other requests
• Advantages
  • Easy to understand
  • Lightweight payloads: tied to actions
  • High performance: action oriented
• Disadvantages
  • Discovery is difficult
  • Limited standardization
  • Leads to function explosion

GraphQL APIs

• Best when needing query flexibility
• Query language for APIs
• Expose single endpoint as entry point
• Client defines structure of data that is required and server returns exactly that structure
• Typically only GET and POST are supported
• Advantages
  • Saves multiple round trips
    • Client can define exact data required
    • Client can request multiple nested level of data in a single call
  • Avoids versioning
    • Can add fields without breaking existing queries
    • Can deprecate existing fields by doing log analysis of usage of fields
  • Smaller payload size
    • Client define exactly what is needed
• Disadvantages
  • Added complexity: Could get complicated depending on data
  • Optimizing performance is difficult
  • Too complicated for a simple API

[jiaqing-tee]

API Paradigms: Event Driven Type

Title: Webhooks vs Websockets vs HTTP Streaming - Which Event-Driven API to use? Link: https://youtu.be/6RvlKYgRFYQ

Takeaways

Types of event driven APIs

1. WebHooks: Trigger the server to send events to pre-defined client endpoints
2. WebSockets: Bi-directional communication between clients and servers
3. HTTP Streaming: One-way communication over HTTP

1. WebHooks

• Client register with interested events and receive callback URL
• Callback URL is by client for API provider to send updates
• Disadvantages
  • Failures: Ensure delivery through retries
  • Firewalls: Apps running behind firewalls can send. but receiving can be tricky
  • Noise: Typically, each webhook represents a single event. Many events in a short time can be noisy

2. WebSockets

• Client send HTTP request handshake
• Server acknowledges request and send upgrade response
• Upgrade communication to a long-lived tcp connection: Both client and server can communicate bi-directionally
• Use case
  • Chat applications
  • Games
• Advantages
  • Bidirectional low latency communication
  • Reduced overhead of HTTP requests
• Disadvantages
  • Clients are responsible for connections
  • Scalability challenges

3. HTTP Streaming

• Server continues to push data in a single long-lived connection
• Client send a request to server
• Server responds but response is indefinite where server can keep sending more and more data
• 2 ways to do this
  1. Chunked
     • Set the transfer encoding header to chunked
     • Common for non-browser clients
  2. Server-Sent-Events
     • For clients that consume data through browser
     • Can use the standardized event source API web interface
• Advantages
  • Can stream over simple HTTP
  • Native browser support
• Disadvantages
  • Bidirectional communication is challenging
  • Buffering