Intermediate Reading #api-docs #rest #http-status

Reading REST Endpoint Docs

5 exercises on reading REST endpoint references — decode methods, path and query parameters, status codes and rate-limit headers.

Key patterns

{id} in a path = a required path parameter
Anything after ? joined by & = query parameters
201 created, 204 no content, 400 bad input, 401 auth, 403 permission, 404 missing, 429 rate-limited
X-RateLimit-Remaining = calls left; Reset = a Unix timestamp

0 / 5 completed

1 / 5

Read this REST endpoint reference:

GET /v1/projects/{projectId}/issues/{issueId}

Path parameters
  projectId  string  required  The project the issue belongs to.
  issueId    string  required  The issue to retrieve.

Responses
  200  OK        The issue object is returned.
  404  Not Found No issue with that id exists in the project.

What does {issueId} in the path represent?

2 / 5

Read this endpoint reference:

POST /v1/orders

Responses
  201  Created       The order was created. The Location header
                     points to the new resource.
  400  Bad Request   The request body failed validation.
  401  Unauthorized  The API key is missing or invalid.
  429  Too Many Requests  Rate limit exceeded.

The call succeeds and the API returns 201. What does that specifically tell you?

3 / 5

Read this endpoint reference:

GET /v1/products

Query parameters
  category  string   optional  Filter by category slug.
  limit     integer  optional  Max items to return. Default 20, max 100.
  page      integer  optional  Page number, starting at 1.

You want the second page of results, 50 items per page, filtered to "books". Which request matches the docs?

4 / 5

Read this rate-limit note from the docs:

Rate limits
  Authenticated requests: 600 per minute per API key.

Every response includes:
  X-RateLimit-Limit      600
  X-RateLimit-Remaining  17
  X-RateLimit-Reset      1718539200   (Unix epoch seconds)

When Remaining reaches 0 the API returns 429 until Reset.

You read X-RateLimit-Remaining: 17 on a response. What does it mean?

5 / 5

Read this error section:

DELETE /v1/users/{userId}/sessions/{sessionId}

Responses
  204  No Content    The session was revoked successfully.
  401  Unauthorized  Authentication is missing or invalid.
  403  Forbidden     You are authenticated but may not revoke
                     sessions for this user.
  404  Not Found     No such session for this user.

An authenticated admin tries to delete another user's session and gets 403, not 401. Why?