DiscoverText API - Responses

Getting Started

All response formats are in JSON and should be of Content-Type: application/json.

Individual Objects

When retrieving an individual object (for example, a project item), a single JSON object will be returned: 

{
    id: {project_id},
    name: "{project_name}",
    timestamp: "{timestamp}",
    href: "{url_to_the_item}",
    links: [{zero to many link items, see below}]
}

An object may include one or more link objects. Each link object returned for a response will include a name and a href URL for the link. For example: 

... links: [
    {
        name: "next",
        href: "https://api.discovertext.com/api/v1/projects?offset=15&limit=10"
    }, ...
]

Collections

When retrieving a collection of objects, in addition to the page of items returned, there will be metadata (including the total count of items) and a set of possible links returned. The (count) field of the metadata should have the total count of items in the collection itself (not just the items returned in the current page). The links may include URLs to navigate through the pages of results (see below). 

{
    meta: {
        count: (item count),
        offset: (current offset),
        limit: (current limit)
    },
    items: [... array of item objects ...],
    links: [... array of links ...]
}

When querying collection types, you can pass query string parameters for the "offset" to set the start item number, and "limit" to determine how many items come back. For example, the following will query the projects list endpoint starting at item number 5, returning a maximum of 10 items: 

https://api.discovertext.com/api/v1/projects?offset=5&limit=10

You can also control the sort field and direction by providing a "sort" parameter. The format of the parameter value should be in the form of "{field}:{direction}". For example, to sort the above example by the project name in ascending order: 

https://api.discovertext.com/api/v1/projects?sort=name:a

... or, in descending order: 

https://api.discovertext.com/api/v1/projects?sort=name:d

For collection listings, you can also filter by item names, by providing a name={name filter} parameter. This will result in the results being filtered by item names that have the specified text in them. For example, to return project items that only have the text "test" in the names: 

https://api.discovertext.com/api/v1/projects?name=test

Collection Paging

When you retrieve a collection of objects, the links section may include links to the first, previous, next and last pages of items based on your offset and limit. Each link will have a name and a URL to the page of results. For iterating through all items in a collection, you should start by specifying offset=0 and loop through the next link pointers until there are no more. 

... links: [
    {
        name: "next",
        href: "https://api.discovertext.com/api/v1/projects?offset=15&limit=10"
    }, ...
]

Errors

Standard HTTP REST error codes are returned in the case of a call failure. These include: