Overview
https://api.theca.com/v1/
Query parameters
Parameters to requests are sent as query parameters. These are described for each request in the following pages. Some parameters are optional, which is denoted with a question mark in the type column. See the following example.
| Parameter | Type | Description |
|---|---|---|
| example | Text | This parameter is a mandatory string. |
| optional | Integer? | This parameter is an optional integer. |
Header parameters
Header parameters must be attached to each API request (though some requests are open for end-users). API requests to
closed requests without a Theca-Client-Token will be rejected with a 403 Forbidden HTTP status.
Do not prefix the headers with X- (this is a deprecated custom for custom HTTP header parameters).
| Parameter | Type | Description |
|---|---|---|
| Theca-Client-Token | Text | A long string that uniquely identifies each client. Provided by Theca. Note that tokens may be revoked by Theca, e.g., if they are compromised or if a token generating service is implemented in a future version of the API. |
| Theca-User-Token | Text | Provided by clients to identify users through system requests. Requests using the same session token will belong to the same session. The provided token will be one-way encrypted (i.e., hashed). Though, it is still not recommended to use sensitive user data for this parameter, such as e-mails or usernames. Internal user IDs or session tokens are both recommended. The maximum size is 255 bytes, the remainder will be discarded. It is used for filtering bot traffic from statistics and improving the search results. |
Formats
Search result data can be returned in either application/json or application/ld+json format. The client chooses which format to use with the HTTP Accept header parameter.
Supported formats:
Accept value | Description |
|---|---|
| application/json | The data will be returned in RFC8259 JSON standard. The charset is always UTF-8 and no characters except " and \ will be escaped. JSON is the default if no Accept parameter is provided or if / is used. When there are multiple possible return values, the @type-field is used to disambiguate which type is the currently returned one. |
| application/ld+json | Returned data follows the LD-JSON RDF format from https://schema.org/. The data will have no Theca extensions, so ItemList will be used instead of ResultList. The structure is equivalent to application/json but the @type of all objects are always included which might make development easier. The data returned can be validated at https://validator.schema.org/. Note that properties with the enum type will have values prefixed with https://schema.org/ as per the specification. For example, when using LD-JSON the item availability property of in stock will be just "availability": "InStock" for application/json but will be "availability": https://schema.org/InStock for LD-JSON. |
You can place LD-JSON content in a script tag on HTML pages to have content from Theca's API be searchable from other
search engines. A good way of complementing inspirational content with a dynamic yet SEO friendly product listing.