Skip to main content

API Fundamentals

An API (application programming interface) is a set of rules that define how applications or devices can connect to and communicate with each other. A REST API is an API that conforms to the design principles of the REST (Representational State Transfer) architectural style.

The Showpad API is a RESTful client-server API, a software architecture that allows communication between clients and servers over the Internet using HTTP methods, with a focus on stateless interactions and resource-based URLs.

A resource is the core entity within the Showpad API. It is defined by an ID, a type, a collection of attributes, and a series of relationships connecting it to other resources.

Data Format

All data created, updated, or retrieved via the Showpad API must be in JSON encoded with UTF-8.


In a basic REST API setup, a client sends an HTTP request to the Showpad server via a URL, which processes it and answers with an HTTP response. The URL identifies which resource or collection of resource links you want to access.

HTTP Methods

Showpad uses the following HTTP methods to map CRUD (Create, Retrieve, Update, Delete) operations to HTTP requests.

GETRetrieves the representation of a single resource or a list of resources.
HEADSame as GET, but without the response body.
POSTCreates or updates an instance of a resource.
PUTUpdates or replaces an existing resource.
DELETEDeletes an instance of a resource.

Request Headers

Request headers are essential components that carry extra information within the HTTP header of a request, providing crucial details and configurations relevant to that particular request.

One key header parameter is Content-Type, which specifies the data format being sent. They help both the sender and receiver understand how to process and interpret the data.

The following table describes the available values for the Content-Type parameter:

Content TypeNotes
application/www-url-encodedUsed to submit data in key-value pairs encoded as a URL string. Suitable for simple data updates.
multipart/form-dataUsed to submit data in a structured format, including files. Suitable for uploading files or complex data.
application/jsonUsed to submit data in JSON format. Suitable for structured data that needs to be parsed and processed by the server.

See the specifications for API v3 and API v4 to know which header is supported for which API.

Query Parameters

You can include parameters in your requests to control the returned data. Query parameters are attached to the end of the URL path. The following parameters are available for Showpad API:

ParameterRequest TypeDescriptionExample
limitGET ResourceLink CollectionLimits the number of retrieved resources.A limit of 25 will only return 25 resources.
offsetGET ResourceLink CollectionOffsets the retrieved Resource Links.An offset of 3 will skip the first three results.
fieldsGET Resource
GET ResourceLink Collection
A comma separated list of attributes to be returned in the response. Typically used to make the response lighter.Specifying id as a field parameter would retrieve a collection containing only ids.

Discover the specific query parameters for each API endpoint by referring to the specifications for API v3 and API v4.

Response Codes

Showpad uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • Codes in the 2xx range indicate success.

  • Codes in the 4xx range indicate an error based on the information provided in the request. Errors can be caused by many factors, such as invalid parameters, authentication errors, and rate limits.

2xx Codes

200OKThe request was successful.GET /users.json will return a collection of user links.
201CreatedThe resource was created.POST /users.json (if the data entered was valid).

4xx Codes

400Bad RequestThe request is malformed.
401UnauthorizedThe request lacks valid authentication credentials.An incorrect or expired OAuth2 access token was sent.
403ForbiddenThe request uses credentials that are not authorized for access.Divisions are only accessible by division-enabled organizations.
404Not FoundThe requested resource could not be found.Specifying an non-existent ID.
405Method Not FoundReturned when an invalid HTTP method is used.POST /tickets.json is unsupported.
409ConflictThe request conflicts with the current data.Creating a user with a non-unique username.
429Too Many RequestsToo many requests have been sent within a specific amount of time.

5xx Codes

500Internal Server ErrorThe server encountered an unexpected condition that prevented it from fulfilling the request.