Skip to content
academia.sh
tr
Log in

Course Intermediate

Web API Design

By the end of this course

Start course

01

API Styles

Different interface styles that meet the same need: the notion of a contract and of compatibility, a comparison of resource-based, remote procedure call, and query-based approaches measured by request count and bytes transferred, REST principles, binary protocols, and communication outside the request-response pattern.

  1. 01 What Is an API What makes an interface a contract: the consumer's unwritten assumptions, defining compatible and breaking change by consumer behavior, the different response a tolerant reader and a strict reader give to the same change, and who owns the contract.
  2. 02 Comparison of API Styles Three styles that meet the same job: resource-based, remote-procedure-call style, and query-based approaches are written for the same scenario and compared by measuring request count, bytes on the wire, and the used share of carried fields; the lesson shows which side has to change when the requirement changes.
  3. 03 REST Principles The set of constraints behind the resource-based style: demonstrating statelessness by testing the same request in two separate processes, measuring the uniform interface with a client that does not know the resource name, the effect of cacheability with an entity tag on bytes carried, and how a layered system follows from these constraints.
  4. 04 Remote Procedure Call and gRPC The approach that writes the contract first: a validator generated from a schema file, the field number being the wire's identity, a byte comparison between a custom binary framing and the text format, and how gRPC brings this design together with stream types.
  5. 05 GraphQL Client-driven query over a single endpoint: the type system the server publishes, validating the query against the schema before it runs, per-field resolution, and the partial success response that results when one field errors; reusing the same document with variables.
  6. 06 Legacy Protocols The design and legacy of envelope-based protocols: separating header from body, carrying the operation name inside the envelope, reporting errors in the envelope instead of the transport layer, how the envelope's cost changes with record count, and which of today's interface decisions were inherited from here.
  7. 07 Synchronous and Asynchronous APIs Communication forms outside the request–response pattern: event stream, long polling, and short polling are compared on the same event sequence by connection count, bytes carried, and delivery delay; a long-running job is modeled with an accepted request and a separate status resource.

02

Resource and Contract Design

Turning domain concepts into resources, URI layout, mapping HTTP methods and status codes correctly, body format, pagination, filtering, field selection, idempotency keys, and link-oriented responses.

  1. 01 Resource Modeling Turning domain concepts into addressable resources: an endpoint list that grows with action names, modeling an operation as a resource's state change, computed resources with no table of their own, and the cost of choosing an identity.
  2. 02 URI Design The path layout of resource addresses: the division of labor between path and query part, naming collections and singular resources, the clash between static and parameter segments, the parent segment of nested paths, and the canonical-address decision.
  3. 03 Correct Use of HTTP Methods The promises a method carries: a safe method not changing data, and an idempotent method producing a single effect when repeated; testing each property by counting rows in the database, PATCH's increment and assignment faces, and the identity choice between PUT and POST.
  4. 04 Status Code Selection Answering the same set of scenarios with two different code mappings and measuring the difference on the client: distinguishing close codes, the meanings of the 2xx family, the silent success a wrong mapping produces, and retries spent for nothing.
  5. 05 Request and Response Bodies The contract value of body format: one spelling for field naming, the silent loss of large integers and decimal amounts, writing dates with zone information, separating a missing field from an empty value, and the envelope decision for collection responses.
  6. 06 Pagination Serving a collection in pieces: the repeats and skips offset-based pagination produces when a record is inserted in between, cursor-based pagination not drifting under the same scenario, and deep pagination's cost in query plan and duration.
  7. 07 Filtering, Sorting, and Search Designing query parameters: translating filter and sort names to columns through an allowlist, carrying client values with bound variables, rejecting requests outside the allowlist, and how sort ties cause pagination to lose records.
  8. 08 Partial Response and Field Selection Letting the client take part in a representation's level of detail: measuring over- and under-fetching in request count and bytes, building field selection and expansion through an allowlist, and the cost this flexibility adds to the contract.
  9. 09 Idempotency Keys The idempotency key that prevents a repeated effect on retry: matching the key to its scope and a body digest, a second request with the same key replaying the first response, rejecting a conflict from a different body, and the key store's lifetime.
  10. 10 Connection-Based Responses The response carrying navigation and action links within itself: walking pages by following only the next link, action links that open and close based on a resource's state, and measuring the client's address-building burden.

03

Errors, Versions and Documentation

Binding error responses to a single shape, reporting field-level validation, path-, header- and content-based versioning, detecting breaking changes from a schema diff, measuring the deprecation window, and testing the contract with machine-readable documentation, contract tests and mock servers.

  1. 01 Error Response Format The cost to the client of improvising the error body per endpoint, the five core fields of the standard problem details format, and verifying with a check that a single-layer problem catalog produces the body.
  2. 02 Validation Errors Adding a field-level error list to problem details, the request-round difference between stopping at the first error and collecting all of them, and the body path rule that makes field names match the client's input boxes.
  3. 03 Versioning Strategies Publishing two versions of the same resource on a single server, the measured equal cost to client code of path-based, header-based, and content-based versioning, and the real difference that comes from whether intermediaries can tell versions apart.
  4. 04 Backward Compatibility The same change classified oppositely in the request and response directions, a differ that compares two schema versions and detects breaking changes, and deriving the version number from the diff instead of from argument.
  5. 05 Deprecation Policy Announcing deprecation in the response itself, collecting per-consumer version telemetry, and calculating the consumer count and traffic share remaining on the old version at the end of the transition period.
  6. 06 Machine-Readable Documentation Writing the contract as a schema, producing both a validator and human-readable documentation from the same definition, and catching at runtime the case where the server's actual response diverges from the definition.
  7. 07 Contract Tests Writing consumer expectations to a file, running them against the provider, showing which consumer's test fails on a breaking change, and calculating the impact scope before the change is made.
  8. 08 Mock Servers Writing a server that produces sample responses from a schema, developing the client against it, measuring that the same code works once it moves to the real server, and counting the cases the mock server hides.

04

GraphQL in Detail

Building the type system, the three operation kinds, per-field resolvers, query reuse through fragments and variables, the measured solution to the N+1 problem through batch loading, the cursor-based connection model, field-level authorization and partial errors, query cost limits, and the caching consequences of the HTTP transport.

  1. 01 Schema and Type System Defining object, scalar, enum, interface, and union types, parsing the query document, and the schema catching errors by validating the query before it runs.
  2. 02 Query, Mutation, and Subscription The three operation types' execution rules, the measured result of running mutation fields sequentially on a single-copy book, and a subscription applying the same selection set more than once over time.
  3. 03 Resolvers The resolver's four inputs, what the default resolver does, execution proceeding level by level, and measuring the resolver-call count and data-source round-trip count a query produces.
  4. 04 Fragments and Variables A fragment gathering a repeated selection set into one place, the resolver-call drop from merging fields in overlapping fragments, and variables fixing the number of distinct documents.
  5. 05 N+1 Problem and Batch Loading The data-source round-trip count growing together with list length, a loader layer that merges calls from the same tick into a single round trip, and a measurement dropping from 101 round trips to 3.
  6. 06 Pagination Patterns Building the cursor-based connection model, separating edge from node, the measured behavior difference between offset and cursor pagination while a list changes, and pagination multiplying across nested lists.
  7. 07 Error Handling and Authorization Collecting errors at the field level, an error returning in the same response as partial data, an authorization layer that wraps resolvers, and measuring how a gap propagates upward through required fields.
  8. 08 Query Cost and Depth Limit Query depth growing without bound in a cyclic type system, a cost ceiling computed before running, and a measurement showing the depth limit alone is not enough.
  9. 09 GraphQL over HTTP Transport over a single endpoint, the caching difference between POST and GET, persisted documents, and measuring the information a single address leaves for intermediaries and logs.

Start typing to search.

↑↓ ↵ Esc navigate · open · close