All basics

Base URL / Endpoint

Base URL / Endpoint

• The root address where the API lives.

• Example:

  • https://api.github.com

  • http://localhost:3100/loki/api/v1

Resources / Paths

Resources / Paths

• APIs are organized by resources (nouns).

• Example (Loki):

  • /loki/api/v1/labels → labels resource

  • /loki/api/v1/query → query resourc

Parameters

• Path Parameters → part of URL

• /users/{id} → /users/123

• Loki: /loki/api/v1/label/{name}/values

real-time path params

• id → resource identifier (/users/45)

• username → /profile/johndoe

• orderId → /orders/1001

• name → /categories/shoes

• region or country → /weather/india

User profile:

/users/{user_id} → /users/12345

Product details:

/products/{product_id} → /products/9876

Loki example:

/loki/api/v1/label/{name}/values → /loki/api/v1/label/job/values

======================================================

• Query Parameters → after ? in URL

  • /query?limit=100&direction=backward

Common query params in APIs

• Pagination

  • page=2 → second page of results

  • limit=50 → 50 results per page

  • Loki: limit=100

• Sorting

  • sort=asc or sort=desc

  • sortBy=date

• Filtering

  • status=active

  • category=shoes

  • level=error (Loki: {level="error"} inside query)

• Searching

  • q=keyword or search=apple

  • Loki: query={job="varlogs"}

• Date/time range

  • start=1692000000&end=1692003600

  • Loki: supports start, end

Common query params in APIs

• Pagination

  • page=2 → second page of results

  • limit=50 → 50 results per page

  • Loki: limit=100

• Sorting

  • sort=asc or sort=desc

  • sortBy=date

• Filtering

  • status=active

  • category=shoes

  • level=error (Loki: {level="error"} inside query)

• Searching

  • q=keyword or search=apple

  • Loki: query={job="varlogs"}

• Date/time range

  • start=1692000000&end=1692003600

  • Loki: supports start, end

• Body Parameters (usually in POST/PUT/PATCH)

  • JSON or form data sent in request body.

  {
    "query": "{job=\"varlogs\"}",
    "limit": 20
  }

Headers

Headers

• Metadata about the request or response.

Common ones:

• Content-Type: application/json (data type)

• Authorization: Bearer <token> (auth)

• Accept: application/json (what format you want back)

Authentication & Authorization

Authentication & Authorization

How the API checks who you are and what you can do:

• No Auth → open/public APIs

• API Key → ?apikey=XYZ or in headers

• Bearer Token (JWT/OAuth2) → Authorization: Bearer <token>

• Basic Auth → username + password

• Custom Headers

Request Body

Request Body

• Data you send in POST/PUT/PATCH.

• Usually JSON.

• Example (Loki POST query):

  {
    "query": "{job=\"varlogs\"}",
    "limit": 100
  }

HTTP Methods

HTTP Methods

Each method represents an action:

• GET → retrieve data

• POST → send data / create something

• PUT → update/replace

• PATCH → partial update

• DELETE → remove

Responses

Responses

• Status Code → tells what happened

  • 200 OK → success

  • 201 Created → resource created

  • 400 Bad Request → wrong input

  • 401 Unauthorized → bad/missing auth

  • 404 Not Found → resource doesn’t exist

  • 500 Internal Server Error → server bug

• Response Body → usually JSON

  {
    "status": "success",
    "data": { ... }
  }

Others

Pagination

• When data is too big, APIs give results in pages.

• Handled via:

  • Query params: ?page=2&limit=50

  • Response: "nextPageToken": "abc123"

👉 Loki handles large results via limit + direction.

---

10. Rate Limiting

• APIs restrict requests per second/minute.

• Response headers may include:

  • X-RateLimit-Limit

  • X-RateLimit-Remaining

---

11. Error Handling

• APIs give structured errors.

• Example:

  {
    "status": "error",
    "errorType": "bad_data",
    "error": "invalid query expression"
  }

---

12. Versioning

• APIs evolve, so versions are added in path or headers.

• Example:

  • /api/v1/...

  • Accept: application/vnd.github.v3+json

👉 Loki uses /api/v1.

---

13. Caching

• APIs may cache results.

• Controlled via headers:

  • ETag

  • Cache-Control: no-cache

---

14. Filtering, Sorting, Searching

• APIs let you refine data with params:

  • /users?sort=name&order=asc

  • /logs?level=error

---

15. Webhooks / Streaming (optional)

• Some APIs push data to you instead of polling.

• Loki doesn’t do webhooks, but supports streaming queries via WebSockets.