API & Type Conventions

API Conventions

MUST represents a non-optional action, setting, or response.

MAY represents an optional action, setting, or response.

SHOULD represents a preferred, but still optional, action, setting, or response.

SHOULD NOT represents an action, setting, or response that is not recommended. Individual use cases may require perform the action, setting, or response but the consequences may not be intended.

MUST NOT represents a action, setting, or response that is not allowed.

WILL represents a mandatory action, setting, or response that is to be performed.

  • Index and type names   MUST NOT start with an _. These names may contain a -, but SHOULD NOT contain a _.
  • Names of search engines, indexes, or types WILL be converted into a “slug”. This slug consists of lower case letters, with white space and other special characters convered to a -. For example, the name “My Test Engine” WILL have a slug of the form “my-test-engine”. This version of the resource’s name will never change once it’s created and is only used as a unique identifier of the resource regardless of future changes to it’s data.
  • FIeld names within JSON documents SHOULD NOT start with an _. These names MAY contain a -, a _, or whitespace.
  • The default response content type is JSON. Other formats MAY be request by specifying a supported mime type in the Accept header. For example, setting Accept to application/xml will request an XML response.
  • Auth credentials MAY be passed via HTTP Basic authorization. If they are not passed via HTTP Basic authorization, they MAY be passed via the HTTP headers X-Dragonglass-User and X-Dragonglass-Engine
  • Response MAY contain a “links” attribute (and sometimes several entries when dealing with lists of objects). Items with the “links” list are URLs MAY be used for further API calls based on desired action. Available actions MUST be defined with the “rel” attribute.
  • GET operations are idempotent and repeatable. GET parameters MUST be passed as URL parameters.
  • POST operations are used for creating new resources. If a POST is performed against a URL that represents a unique resource, it WILL be interpreted as a request to update the resource, instead of creating a new resource.
  • PUT operations are used for updating a resource. Such an operation MUST be performed against a unique resource.
  • DELETE operations are used for deleting a resource. They MAY operate against a unique resource. They MAY also operate against a list or group of resources

Type Conventions

A Dragonglass type definition is created through a JSON DSL. A type MUST have a name, and SHOULD contain at least one field. A field MUST have a name, a data type; it MAY have data type modifiers.

Valid data types are: string, integer, float, bool, datetime, location, address, postal, and attachment.

A string is a sequence of letters, numbers, and special characters (such a . or -). It MAY include spaces, tabs, and carriage returns. A string MAY contain additional type modifiers. Valid modifiers are is_facetable, is_searchable, or is_completable. is_searchable defaults to true, is_facetable and is_completable default to false.

A bool can be represented by the JSON values true or false. It MAY also be represented by the characters ‘t’, ‘f’, ‘y’, or ‘n’.

A datetime can be either a date, or a fully qualified timestamp. It MAY be represented by as text; if so, it MAY include a timezone offset. It may also be represented by an integer, and expressed as the number of milliseconds since the epoch.

A location is a combination of latitude and longitude. It MUST contain both values within a JSON map.

Address is a combination of strings that represent a mailing or physical address. It MUST be presented by a JSON map. Indexing an address field WILL create an additional field in your data type that will be a location.

Postal is a string. Since some postal codes are represented entirely as numbers, this type prevents Dragonglass from incorrectly inferring this field as a numeric type.

Attachment represents the contents of a file. Since JSON cannot contain binary data, the contents of the file must be base64 encoded. This type allows for the parsing and searching of arbitrary files.

Example JSON Data Type Definition:

{ “my-type”: { “field1”: { “type”: “integer” } }, { “field2”: { “type”: “string”, “is_facetable”: true } } }

This defines a new data type my-type, with 2 fields. field1 is an integer. field2 is a string that is both searchable (since that modifier defaults to true), and facetable.