help:common url parameters

Table of Contents

With the URLs used for navigation around the site, there are several common URL parameters which can be used.

Any format

The parameters can be used on any format, which includes HTML, ATOM, XML, and JSON.

Page

The method by which different sections of the database can be viewed. This parameter can be either numeric or sequential. For both the name of the parameter key is "page".

|Numeric|

Used on the index views, it determines the starting position of the records shown. It is an integer that must be greater than zero. Any ordering parameter available for the various records may be used.

  • Example: page=1

The following is the equation used for the record starting position.

(page - 1) * limit

Where limit is the number of records shown per page, as explained later below.

|Sequential|

Uses the record ID numbers instead to determine the starting or ending positions for the records. It is an integer that is prefaced with an "a" or "b". When used, the order of the records is forced as ID descending, regardless of any ordering parameter

  • Example: page=a12345

When prefaced by "a", the integer marks the ending position where records must be above that ID.

When prefaced by "b", it marks the starting position where records must be below that ID.

Limit

The number of results to show per page. It is an integer that must be greater than zero. The name of the parameter key is "limit".

  • Example: limit=100

All search parameters use URL hash format (Help:Hash syntax) where "search" is the base object.

Example: search[PARAMETER]=VALUE

|Custom order|

Sets the order of the results by the order of the values requested.

  • search[order]=custom
  • search[id]=2,3,1,4

The above would return items with ID's of 2, 3, 1, 4 in that order.

Both parameters must be present to perform this type of search. Only the comma-separated version of the ID parameter is supported.

XML/JSON

These parameters are only available with the XML and JSON formats.

Only

Determines the list of attributes that will be returned. The attributes must be comma separated, though can be in any order. The name of the parameter key is "only".

  • Example: only=id,name,created_at
[
  {
    "id": 200403,
    "created_at": "2020-03-15T17:16:15.772Z",
    "name": "spica_s"
  }
]
|Associated attributes|

The only parameter may also be used to included other records that have associations with that particular record type. To include the record, the name of the association must be added to the comma separated list like any other attribute.

  • Example: only=tag

When an associated attribute is included, the entire record of that attribute is added to the hash of the record returned.

[
  {
    "tag": {
      "id": 1560500,
      "name": "spica_s",
      "post_count": 1,
      "category": 1,
      "created_at": "2020-03-15T17:16:15.771Z",
      "updated_at": "2020-03-15T17:16:15.771Z",
      "is_locked": false
    }
  }
]
|Nested only|

The only parameter can be further specified onto the associated attributes. This is indicated by the use of square brackets "[ ]", where the square brackets are next to the name of the associated attribute. The only parameters are a comma separated list inside the square brackets.

  • Example: only=tag_alias[consequent_name,status,forum_topic_id]
[
  {
    "tag_alias": {
      "consequent_name": "claire_stanfield",
      "status": "active",
      "forum_topic_id": null
    }
  }
]
|Nested attributes|

Associated attributes can be further specified on the associated attributes. Like above, the name of these associated attributes must be included in the square brackets.

  • Example: only=post[comments]
[
  {
    "post": {
      "comments": [
        {
          "id": 1988814,
          "created_at": "2020-03-13T20:28:53.565Z",
          "post_id": 3770941,
          "creator_id": 561532,
          "body": "Bomp",
          "score": 0,
          "updated_at": "2020-03-13T20:28:53.565Z",
          "updater_id": 561532,
          "do_not_bump_post": false,
          "is_deleted": false,
          "is_sticky": false
        }
      ]
    }
  }
]
|Recursion|

The only and associated attributes can be chained through all available attributes on all available models.

  • Example: only=artist[urls[url]]
[
  {
    "artist": {
      "urls": [
        {
          "url": "https://shirokurokun.tumblr.com"
        },
        {
          "url": "https://twitter.com/pancakehotmot"
        }
      ]
    }
  }
]

One imposed limitation on this is that a particular record type may only be included twice down any particular attribute chain.

  • Example: notes --> post --> notes -X> post

This is to prevent endless recursion.

See also