What is an API?
An API, or application programming interface, defines ways software can interact with another application or component. It can expose data or operations, not just retrieve information. The MDN definition includes browser features and other software interfaces as well as third-party services. This page focuses on HTTP-based integrations.
In that setting, an endpoint identifies the request target, while the method expresses the requested operation. HTTP semantics distinguishes methods such as GET, POST and PUT. The provider's contract tells you which operations the endpoint supports and what inputs and responses it uses.
Specify the operation before choosing a connector
“Connect the catalogue” is an incomplete brief. Do you need to read item descriptions, change availability or create a record? Write down the source, destination, required fields and accepted result. Assign someone to investigate failures rather than assuming a connection keeps every system synchronized.
Read the product documentation and confirm the permissions available to your account. Check that the required operation is exposed and that the chosen connector supports its fields. Record any missing capability before committing to the workflow.
Read the method, target and response
HTTP's GET method requests a selected representation of a resource. POST asks the target to process the supplied representation according to its own semantics, which can include creating or appending data. PUT asks to create or replace the target's state. Read these distinctions before treating every request as a read or every update as interchangeable.
A representation is the information transferred about a resource. The Content-Type header identifies its media type and how the recipient should process it. JSON is a possible format, not the definition of an API. Check the documented response structure rather than inferring it from the tool's name.
Interface, style, method and notification
These terms describe different parts of an integration. Use their purpose to organize questions for the provider.
| Term | What it describes | Question to ask |
|---|---|---|
| API | The software interface and its available interactions | Which data and operations are actually exposed? |
| REST | An architectural style with constraints including a uniform interface | What resource and representation contract is documented? |
| HTTP method | The requested operation on a target resource | Is this retrieval, resource-specific processing or replacement? |
| Webhook | An event-triggered delivery to a configured receiver | Which events, payloads and failure behavior does the sender document? |
In Roy Fielding's description of REST, components act on resources through representations, and a media type describes a representation's data format. REST is not a synonym for JSON. Calling an HTTP endpoint that returns JSON does not, on its own, establish the architectural constraints.
A fictional catalogue request
Imagine a fictional public catalogue that lists items in a category. Its hypothetical contract uses a relative target and returns an items array with an identifier and label. The partial request and response below illustrate that contract; they are not complete HTTP messages.
GET /catalog/items?category=ceramics
200 OK
Content-Type: application/json
{"items":[{"id":"mug-blue","label":"Blue mug"}]}
Read the request and result together: the category parameter asks for ceramics, and the returned item has an identifier and label for the receiving workflow to map. The Content-Type labels the representation. For GET, HTTP's 200 semantics describes successful transfer of a representation of the target resource.
Before using a real equivalent, inspect the returned fields, any pagination instructions and how the provider documents failures. Check whether the receiving workflow interprets the item identifier consistently. A parseable response is only one part of verifying that the requested business operation was fulfilled.
Polling and webhooks can work together
Polling means making requests at intervals to check for information. A webhook changes when a sender delivers a notification; it does not make an API exclusively a pull mechanism. GitHub's documentation, for example, describes subscribing to events and sending an HTTP request with event data to a configured URL.
Choose based on the workflow and documented capabilities. A scheduled read might suit an occasional report; an event subscription might suit a notification. Record the sender's delivery and retry behavior, and how the receiver will reconcile state after a missed notification.
Make the handoff reviewable
Keep the operation, documented version, required fields, access requirements, expected response and failure owner together. Ask which identity a credential represents and which actions it permits. If the provider offers a test environment, use it to check the workflow before deployment.
For troubleshooting, define the information you need and who may inspect it. OWASP's logging guidance discusses event context and identifiers, while recommending that access tokens, passwords and sensitive information are not recorded directly. Use a permitted summary or appropriately protected fields instead of dumping every header and payload.
A retry needs operation-level reasoning
HTTP describes an idempotent method as one whose repeated identical requests have the same intended server effect as a single request. That does not mean every response will be identical or that the server cannot log each attempt. A repeat-safe operation and an unchanged response are different properties.
HTTP's retry guidance says a client should not automatically retry a non-idempotent request unless it can establish that the operation is actually idempotent or that the original request was never applied. Before repeating a write, check the documented operation and how duplicate effects are prevented or detected.
A Retry-After header addresses waiting before a follow-up request. It is not proof that repeating a write is safe. Treat timing and operation safety as separate checks, and retain an unresolved outcome for investigation rather than retrying every failure blindly.
Related terms
A content management system is an application you might connect. Workflow Automation covers the wider sequence of actions: when to request an operation, what to do with the result and who investigates a failure.
Sources and scope
MDN supplies the interface definition, HTTP semantics supplies method and retry distinctions, and Fielding describes REST. GitHub illustrates its own webhook model; OWASP supplies scoped logging guidance. The table's practical questions are an editorial reading aid.