List APIs, without the mystery.

An application programming interface, or API, describes how one piece of software can request information or ask another piece of software to perform an operation. A list API focuses on a collection: notes, tasks, contacts, events, bookmarks, or another kind of record. Start by defining what one record means. The shape of an array is less important than the meaning of the objects inside it.

Records, collections, and relationships

A record is an individual item. A collection groups items. A relationship connects them. In a task workflow, the task is a record, the project is a collection, and project membership is a relationship. Keeping those ideas separate lets an item move without losing its identity.

Use stable identifiers rather than editable labels. A task named “Weekly review” can be renamed, and several tasks can have that name. An identifier gives an integration a durable reference. Keep the source account with an imported identifier whenever its uniqueness is limited to that account.

Reading a small JSON example

JSON represents data with objects, arrays, strings, numbers, Booleans, and null values. This synthetic file describes a task list. It is a static learning example, not a live API response or a promise that the same fields exist in another provider’s API.

{
  "example": true,
  "list_id": "list_001",
  "title": "A thoughtful launch",
  "items": [
    {
      "task_id": "task_001",
      "title": "Review the guide structure",
      "status": "completed",
      "due_date": "2026-09-01",
      "version": 1
    },
    {
      "task_id": "task_002",
      "title": "Check the sample data",
      "status": "open",
      "due_date": "2026-09-04",
      "version": 1
    }
  ],
  "next_cursor": null
}

Download this example JSON and compare it with the to-do list field model.

Reads and writes have different consequences

A read retrieves information. A write creates, changes, or removes something. Begin a new integration with a read-only view whenever that meets the immediate goal. Before adding writes, decide which system owns each field and what the integration should do when a person changes the same value elsewhere.

HTTP methods express request semantics, but a particular API still defines the exact routes and behavior it supports. Do not invent a working endpoint from a familiar verb and noun. Follow the provider’s current documentation and treat illustrative paths in tutorials as illustrations unless they are explicitly documented as real.

A page is not the entire list

A large collection is often returned in smaller pages. A continuation token tells the client how to ask for the next portion. Treat it as opaque unless the provider says otherwise. Keep the original query configuration with the retrieval run, and do not call a partial import complete merely because its first page succeeded.

Pagination retrieves more of a result set. Incremental synchronization retrieves changes since a previous checkpoint. Those are different processes. A page token should not be assumed to behave like a synchronization token, and a token from one provider should not be expected to follow another provider’s rules.

Authentication is not the whole permission model

Authentication establishes who is making a request. Authorization determines whether that actor may perform the requested operation on the particular record. Plan permissions for list views, individual records, exports, notifications, and background jobs. A hidden button is not an access-control boundary.

Keep credentials out of public HTML, example data, and client-side source files. A real integration needs an appropriate credential-handling design for its environment. This website has no accounts, token storage, or live connections; it explains the decisions without asking you to provide access.

Plan the imperfect request

A request can succeed while its response is lost. Retrying a creation operation without a documented safety mechanism can create duplicates. For an API you control, define an idempotency strategy. For a provider API, follow its actual retry contract and reconcile uncertain results before repeating side effects.

Also plan for incomplete imports, conflicting edits, deleted records, and revoked access. Keep the last completed update distinct from the last attempted update. A visible stale or partial state is more useful than a polished interface that quietly presents old information as current.

Sketch your first workflow

Choose one source, one record type, and one destination. Write down the required fields, the intended audience, the source of truth, and the result you expect from a successful read. Then add one renamed record, one duplicate title, and one interrupted request to your test plan.

Once that small workflow is understandable, move to the topic-specific guide. The list API directory shows the differences between notes, tasks, messages, subscriptions, and relationships. The glossary provides a compact reference when unfamiliar terms appear.