Parse and Construct API Endpoint URLs

API Endpoint URL Structure

REST API endpoints follow URL conventions that encode resource identifiers, actions, filtering, and pagination directly in the URL structure.

Anatomy of a REST API URL

https://api.example.com/v2/users/42/posts?status=published&page=3&per_page=20
\____/ \_____________/ \_/ \___/ \_/ \___/ \_____________________________________/
  |          |          |    |    |    |                  |
scheme    hostname    ver  resource id  sub         query filters
                              resource

Path Parameter Patterns

GET  /users                    → List all users
GET  /users/42                 → Get user 42
POST /users                    → Create a user
GET  /users/42/posts           → List posts by user 42
GET  /users/42/posts/7         → Get post 7 by user 42
GET  /users/42/posts/7/comments → Comments on post 7

Common Query Parameters

Parameter	Purpose	Example
page, offset	Pagination	?page=3 or ?offset=40
per_page, limit	Page size	?limit=20
sort, order	Sorting	?sort=created_at&order=desc
filter, status	Filtering	?status=active
fields, select	Sparse fieldsets	?fields=id,name,email
include, expand	Related resources	?include=author,tags
q, search	Full-text search	?q=javascript

API Versioning in URLs

https://api.example.com/v1/users     → Version in path
https://api.example.com/users         → Version in header (Accept: application/vnd.api.v1+json)
https://v1.api.example.com/users      → Version in subdomain

Building API URLs Programmatically

function buildApiUrl(resource, id, params = {}) {
  const base = new URL("https://api.example.com/v2");
  const path = id ? `/${resource}/${id}` : `/${resource}`;
  const url = new URL(path, base);
  Object.entries(params).forEach(([key, value]) => {
    url.searchParams.set(key, String(value));
  });
  return url.toString();
}

buildApiUrl("users", 42, { include: "posts", fields: "name,email" });
// "https://api.example.com/v2/users/42?include=posts&fields=name%2Cemail"

Authentication in API URLs

Some APIs accept tokens as query parameters (though headers are preferred):

https://api.example.com/data?api_key=abc123
https://api.example.com/data?access_token=xyz789

Security note: API keys in URLs appear in server logs, browser history, and Referer headers. Prefer the Authorization header instead.