What is Response Format?

API & Technical5 min readUpdated Mar 25, 2026

The structured data format used by an API to return results, typically JSON, defining how trademark data is organized and represented.

The response format of an API defines how data is structured and represented in the responses returned to clients. It encompasses the data serialization format (such as JSON or XML), the schema of the response body (field names, data types, nesting structure), the use of HTTP headers for metadata, and the conventions for representing different types of data such as dates, enumerations, and null values. A well-designed response format is consistent, predictable, and self-documenting, enabling developers to build reliable integrations efficiently.

JSON (JavaScript Object Notation) has become the dominant response format for modern REST APIs due to its human readability, compact size, and native support in virtually every programming language. JSON responses consist of key-value pairs organized into objects and arrays, providing a natural way to represent the hierarchical structure of complex data like trademark records.

A comprehensive API response format includes several components beyond the primary data. Metadata about the response itself, such as pagination information, request identifiers, and timestamps, helps clients manage the interaction. HTTP status codes communicate the outcome of the request (success, client error, server error). Response headers convey additional information like rate limit status, content type, and caching directives.

Consistency in response format is paramount. When every endpoint in an API returns responses with the same structural conventions, developers can write generic parsing code that works across the entire API. Inconsistencies, such as one endpoint returning dates as "2026-03-25" and another as "03/25/2026," force developers to write special-case handling that increases complexity and the potential for bugs.

Why It Matters

The response format is the primary interface through which developers interact with an API's data. A poorly designed format creates friction at every stage of integration: during initial development as developers decipher undocumented conventions, during maintenance as inconsistencies require special handling, and during debugging as ambiguous representations make it difficult to identify the source of problems.

For trademark data specifically, response format quality is critical because trademark records contain complex, multi-faceted information. A single trademark record may include text in multiple languages, dates in various formats, status codes specific to different offices, classification data with hierarchical relationships, and image references. The response format must represent all of this information clearly and consistently.

The response format also affects performance. Verbose formats with deeply nested structures and redundant data increase response sizes, which in turn increase transmission time and parsing overhead. Compact formats that convey the necessary information without unnecessary bloat enable faster, more efficient integrations, particularly for high-volume applications that process thousands of responses per hour.

Developer experience is directly shaped by the response format. APIs with clean, consistent, well-documented response formats attract developers and foster a healthy integration ecosystem. APIs with inconsistent, poorly documented formats deter developers and generate support burden. In a competitive market for trademark data services, the quality of the response format can be a differentiating factor.

How Signa Helps

Signa's API returns JSON with one consistent schema across endpoints. A single resource, such as one trademark, comes back at the top level with its id, an object type such as "trademark", and its fields. List and search endpoints return object: "list" with the results in data, a top-level has_more, and a pagination object carrying the cursor for the next page. Searches add a search_meta object describing how the search ran. Every response carries a top-level request_id, except publicly cached reference data such as offices and classifications.

Every trademark record follows the same schema regardless of the source office. Field names use snake_case, such as mark_text, filing_date, nice_classes and office_code. Dates use ISO 8601 (YYYY-MM-DD). Status is a structured object, status.primary (for example active or pending) and status.stage (for example registered or examining), mapped from each office's own status codes.

Search results carry the key facts on each mark, and the retrieve endpoint returns the full record, adding attorneys, images, the complete goods and services, Madrid territory coverage, related marks and provenance. Clients fetch the full record only when they need it.

Errors share one format too: an error object with a stable type (such as validation_error or not_found), a title, the HTTP status, a detail message, a suggestion, and retryable and retry_after fields, plus the request_id. Clients can implement error handling once and reuse it for every endpoint.

The official TypeScript SDK (@signa-so/sdk) ships types for every endpoint and response.

Example

A portfolio management application uses Signa's API to show trademark information to its users. Because every record has the same shape, the team writes one data model that works for marks from any office.

A USPTO record and an EUIPO record both arrive with mark_text, filing_date, nice_classes, owners and status in the same structure. The filing_date is always "2024-06-15", never "06/15/2024" or "15.06.2024", and status.primary is always one of a small set of lowercase values rather than an office-specific code.

The team builds one component that renders any record without per-office logic, and uses the SDK's types so the compiler catches mismatches between the application and the API's responses. When Signa adds an office, its records arrive in the same format.