----- Original Message -----
From: "Adam Price" <notifications@github.com>
To: "theforeman/theforeman.org" <theforeman.org@noreply.github.com>
Cc: "Joseph Magen" <jmagen@redhat.com>
Sent: Friday, October 18, 2013 6:45:19 PM
Subject: Re: [theforeman.org] beginning developer documentation for the v2 api standards (#106)

> +
> +The default root node title is configurable, but defaults to `results`.
> +
> +The collection response contains metadata:
> +
> +* `total` - total number of objects

total number of objects without any search parameters

> +* `subtotal` - number of objects contained within this response

number of objects returned with given search parameters (of cource, if there is no search, the subtotal == total)

> +* `limit` - ???

number of objects returned in API call (for example, if there are a total of 27 objects, and per_page is 20 and you are on page 2, then only 7 objects were for return, so limit is 7)

> +* `offset` - index offset from the first item in the collection
> +* `page` - page number
> +* `per_page` - objects per page
> +* `search` - search term used

I would write "search string" rather than "search term," since it could be "location = TLV and hostgroup = Base" (as Foreman uses the great scoped_search gem -- props to abenari)

> +* `sort`
> +    * `by` - the field that the collection is sorted by
> +    * `order` - sorted in ascending or descending order
> +* `results` - list of objects 

list (or collection) of objects. Number objects returned for special call is equal to "limit"