API Conventions

When specific exceptions are not noted, the behavior described below applies to all horn API methods.

Authorization Header

With very few exceptions, all calls to the horn API require authentication.

Credentials are expected as a bearer token provided in a header, like:

Authorization: Bearer <TOKEN GOES HERE>

Returned Media Type

The horn API will return JSON data. If an Accept header is provided in requests, it should be set to application/json.

Passing Parameters

There are three different ways that horn API calls accept parameters. They are not generally interchangeable, but the parameter type(s) expected for each call is specified in the call documentation.

1. JSON Object in Request Body

   POST methods that take more than one parameter generally expect their parameters as a JSON object in the request body. For example, the Create a channel call expects a name and a description:

   {
     "name": "my new channel",
     "description": "a place to chat with me"
   }
   

2. URL Path Parameter

   Methods that take only a single parameter sometimes look for the parameter in the URL path rather than in a JSON object.

   For example, see Delete a channel, which expects the UUID of the channel to delete at the end of the requested URL.

3. URL Query Parameter

   Query parameters are sometimes used for requests that require more than a single parameter or take optional parameters. (This is most commmon for GET requests that have no request body in which a JSON object could be sent.)

   The List channels call is a good example of this. The call can be made with no parameters:

   GET https://api.horn.co/api/v1_0/channels
   

   Or it can be made with any combination of modifiers (see call documentation for details). The following call will show the second page of 10 results sorted by descending channel creation time:

   GET https://api.horn.co/api/v1_0/channels?limit=10&offset=10&sort=created&order=desc
   

   Note: parameter values containing spaces or special characters need to be URL Encoded.

imgSize Parameter

Many methods take an imgSize parameter, which is used to specify the size of an image returned by a call.

Valid imgSize parameters include:

Parameter	Size
“small”	40x40
“medium”	80x80
“large”	100x100
“xlarge”	130x130
“xxlarge”	175x175
“unfurl”	600x600