Introduction

The Tender API is a JSON REST interface for managing your discussions. It is accessible from any HTTP client with a valid login to an existing Tender site. All posted data should be sent as valid JSON, and all received data will be valid JSON.

The Endpoint

The API for every Tender is accessed is through a single domain. To access the API for Tender's main support site, use https://api.tenderapp.com/help. To use the API for your own Tender, replace "help" with the subdomain of your Tender site. You will need to ensure you're using TLS v1.2 ssl security.

REST API Basics

Tender's API adheres fairly closely to the REST style of HTTP API design. This means that there is a consistent pattern to the resource URLs and HTTP methods used in this API:

GET /resources => list resources
POST /resources => create a new resource
PUT /resources/{resource_id} => update an existing resource
GET /resources/{resource_id} => view a single resource
DELETE /resources/{resource_id} => delete a single resource

The Accept header

Tender's API always returns JSON with the content-type application/vnd.tender-v1+json, so make sure you've included that type in your Accept header.

> curl http://api.tenderapp.com
Invalid Accepts Header: */*, should be: application/json and application/vnd.tender-v1+json

# Now, specify the mime type
> curl -H "Accept: application/vnd.tender-v1+json" http://api.tenderapp.com
{"site_href": "http://api.tenderapp.com/{site_permalink}"}

JSON body

The received data will always be in JSON format. Resources will usually contain these common fields:

• href - URI for the current resource.
• foo_href - URI for the 'foo' action. Each resource may or may not have one or more actions. For instance, the site resource links to the site's discussions, categories, queues, etc.

Collections of resources will actually come in a pagination hash, instead of just an array of objects. For instance, querying for discussions might return a hash that resembles this:

{
  "offset": 0,
  "total": 1069,
  "per_page": 30,
  "discussions": [
    {DISCUSSION}, {DISCUSSION}
  ]
}

From that hash, you can see how many total records are in the collection. You can then retry the request with ?page=2 to get the second page, and so on.

URI Templates

JSON resources that are received from Tender include HTTP references to further API actions available for that resource. These addresses are specified as URI Templates, RFC 6570, and are capable of showing available parameters for any given action.

For example, you can parse the given URL http://api.tenderapp.com/{site_permalink} like this:

# this is ruby, but it should be similar for other languages with URI Template libraries
>> require 'addressable/template'
>> tmpl = Addressable::Template.new('http://api.tenderapp.com/{site_permalink}')
>> tmpl.expand('site_permalink' => 'help').to_s
=> http://api.tenderapp.com/help

In this case, 'help' refers to 'help.tenderapp.com' - you would replace that with the subdomain of your own Tender.

Parsing URI templates is not required, but will help any API libraries that use it learn new resource actions and keep updated URLs in sync.

Good ruby template parsing library: addressable

Paginated Results

All paginated areas of the API take a page parameter that will allow you to page through results.

That's it for the basics, continue on to authentication.