Skip to main content

API Fundamentals

The Showpad API is a RESTful client-server API. In its essence, the term REST is used to indicate the API is based on the principles of:

  • Sending an HTTP request and receiving an HTTP response
  • Using HTTP verbs (GET, POST, PUT, etc.)
  • Interpreting HTTP response codes
  • Resources

HTTP Methods

In a basic REST API setup, an HTTP request is sent to the Showpad server, which processes the request and answers with an HTTP response. The request itself has a number of parameters, important to the Showpad API. It supports the following HTTP methods to map CRUD (Create, Retrieve, Update, Delete) operations to HTTP requests.

MethodDescription
GETUsed to retrieve resources of a collection of resource links
POSTUsed to create or update a resource
PUTUsed to update a resource
DELETEUsed to remove a resource
HEADUsed to retrieve resources of a collection of resource links

Query Parameters

Query parameters are parameters attached to the URL after the path of the URL.

Depending on the type of request, there are a number of standard query parameters:

ParameterTypeAvailabilityDescription
limitGET ResourceLink CollectionV1+Limits the number of retrieved resources (i.e. a limit of 25 will return 25 resources).
offsetGET ResourceLink CollectionV1+Offsets the retrieved Resource Links (i.e. an offset of 3 will skip the first 3 results)
fieldsGET Resource or GET ResourceLink CollectionV1+A comma separated list of attributes to be returned in the response. It is usually used to make the response lighter. E.g. if you only want to find out the ID of resources in a collection, specifying id as a field parameter would only retrieve a collection of ids.

HTTP Response Codes

CodeNameDescriptionExample
200OKReturned when a request successfully executedGET /users.json will return a collection of user links
201CreatedReturned when a resource is createdPOST /users.json (if the data entered was valid)
400Bad RequestReturned when the request is invalid. This is a very general error.
401UnauthorizedReturned when an incorrect access token has been specifiedAn incorrect or expired OAuth2 access token was sent
403ForbiddenReturned when the user does not have enough permissions to access the resource.Divisions is only accessible by division enabled companies
404Not FoundReturned when a resource is not found.Specifying an non-existent ID is specified.
405Method Not FoundReturned when an invalid HTTP method is used.POST /tickets.json is unsupported
409ConflictReturned when the user has entered invalid data.Creating a user with a non-unique username
429Too Many RequestsReturned when the user exceeds the rate limit for a given time frame.
500Internal Server ErrorReturned when a server error occurs.