Weasyl HTTP API =============== Basic endpoints --------------- .. http:get:: /api/version(.format) The current version of Weasyl, in some specified format. The format can be one of ``.json`` or ``.txt``, or omitted for JSON by default. For example:: {"short_sha": "deadbeef"} .. http:get:: /api/whoami The currently logged-in user, as JSON. For example:: {"login": "weykent", "userid": 5756} If there is no current user, the response will be a :http:statuscode:`401`. .. http:get:: /api/useravatar A user's avatar. :query username: The user's :term:`login name`. The result will resemble:: {"avatar": "https://www.weasyl.com/static/user/66/42/8d/0a/3f/8c/5756/avatar.png"} Users without an avatar will get the default avatar icon back. .. http:get:: /api/submissions/frontpage A list of submissions from the front page, respecting the current user's browsing settings. :query since: An :term:`ISO 8601 timestamp`. If specified, only submissions posted after this time will be returned. :query count: If specified, no more than this many submissions will be returned. This will return at most 100 submissions. If *count* is more than 100, at most 100 submissions will be returned. It is possible to receive less than *count* submissions back if too many submissions are filtered by the user's e.g. tag filters. The result will be a JSON array of :ref:`submission objects `. .. http:get:: /api/submissions/(submitid)/view View a particular submission by its ``submitid``. :query anyway: If omitted, the current user's tag filters may cause an error to be returned instead of a submission object. If specified as any non-empty string, tag filters will be ignored. :query increment_views: If omitted, the view count will not be incremented for the specified submission. If specified as any non-empty string while :ref:`authenticated `, the view count may be increased. The result will be a JSON :ref:`submission object `. .. http:get:: /api/users/(login_name)/view Retrieve information about a user by :term:`login name`. The result will be a JSON :ref:`user object `. .. http:get:: /api/users/(login_name)/gallery List a user's gallery by :term:`login name`. :query since: An :term:`ISO 8601 timestamp`. If specified, only submissions posted after this time will be returned. :query count: If specified, no more than this many submissions will be returned. :query folderid: If specified, only return submissions from the specified ``folderid``. :query backid: If specified, only return submissions with a ``submitid`` greater than the ``backid``. This is used in pagination. :query nextid: If specified, only return submissions with a ``submitid`` less than the ``nextid``. This is used in pagination. This will return at most 100 submissions. If *count* is more than 100, at most 100 submissions will be returned. The result will be a JSON object with three keys: *submissions*, *backid*, and *nextid*. *submissions* will be a JSON array of :ref:`submission objects `. *backid* and *nexid* are used in :ref:`pagination `. .. http:get:: /api/messages/submissions List submissions in an :ref:`authenticated ` user's inbox. :query count: If specified, no more than this many submissions will be returned. :query backtime: If specified, only return submissions with a ``unixtime`` greater than the ``backtime``. This is used in pagination. :query nexttime: If specified, only return submissions with a ``unixtime`` less than the ``nexttime``. This is used in pagination. This will return at most 100 submissions. If *count* is more than 100, at most 100 submissions will be returned. The result will be a JSON object with three keys: *submissions*, *backtime*, and *nexttime*. *submissions* will be a JSON array of :ref:`submission objects `. *backtime* and *nextime* are used in :ref:`pagination `. .. http:get:: /api/messages/summary List a summary of notifications for an :ref:`authenticated ` user. The result will be a JSON object resembling:: { "comments": 0, "journals": 3, "notifications": 1, "submissions": 14, "unread_notes": 0 } .. note:: The result of this API endpoint is cached. New information is available only every three minutes or when a note arrives. OAuth2 endpoints ---------------- .. http:get:: /api/oauth2/authorize The standard OAuth2 authorization endpoint. Currently only authorization code grants with callback URIs are supported. :query client_id: The client identifier issued to the consumer by Weasyl. :query redirect_uri: The callback URI the consumer provided to Weasyl before the *client_id* was issued. :query scope: Currently, only one scope is allowed: ``"wholesite"`` :query state: A random unguessable string. :query response_type: Currently, only one response type is allowed: ``"code"``. On a successful authorization, the user agent will be redirected to the *redirect_uri* with query parameters of *code* and *state*. *code* will be a random string used to retrieve the authorization code grant, and *state* will be the same *state* as was passed originally. .. http:post:: /api/oauth2/token The endpoint for fetching and refreshing OAuth2 tokens. :form client_secret: The client secret issued to the consumer by Weasyl. Other form parameters are described for authorization code grants at and for refreshing tokens at . .. note:: Access tokens currently expire after an hour, to be sure to use the provided refresh token before then. .. _submissions: Submissions ----------- A basic submission object resembles:: { "media": {}, "owner": "Caffeinated-Owl", "owner_login": "caffeinatedowl", "posted_at": "2014-02-12T07:33:17Z" "rating": "general", "submitid": 466821, "subtype": "visual", "tags": [ "hunter", "snake", "pi" ], "title": "Tiny Little Pi", "type": "submission", } The *type* key will be one of ``"submission"`` or ``"character"``. The *subtype* key for ``"submission"`` types will be one of ``"visual"``, ``"literary"``, or ``"multimedia"``. The *rating* key will be one of ``"general"``, ``"moderate"``, ``"mature"``, or ``"explicit"``. The *media* key is the submission's :ref:`media `. Slightly different keys are returned for the :http:get:`/api/submissions/(submitid)/view` endpoint:: { "comments": 0, "description": "Itty bitty little snake hunter", "embedlink": null, "favorited": false, "favorites": 3, "folder_name": null, "folderid": null, "friends_only": false, "owner": "Caffeinated-Owl", "owner_login": "caffeinatedowl", "owner_media": {}, "posted_at": "2014-02-12T07:33:17Z", "rating": "general", "media": {}, "submitid": 466821, "subtype": "visual", "tags": [ "hunter", "pi", "snake" ], "title": "Tiny Little Pi", "type": "submission", "views": 6 } The *media* key is the :ref:`media ` for the submission itself, while the *owner_media* key is the :ref:`media ` for the owner of the submission. The *embedlink* key will be ``null`` for ``"visual"`` type submissions and potentially a URL for other submission types. The *description* key is the HTML-rendered description of the submission. The *favorited* key indicates whether or not the current user has favorited the submission. .. _users: Users ----- A user object contains many keys. Some of these keys include: ``media`` The :ref:`media ` of the specified user's avatar and banner. ``profile_text`` The rendered HTML of the specified user's description. ``recent_submissions`` An array of :ref:`submission objects `. ``recent_type`` What kind of submissions are in the ``recent_submissions`` array. Can be one of ``submissions``, ``characters``, or ``collections``. ``relationship`` ``null`` if this is an unauthenticated request or an object representing aspects of the relationship between the current user and the specified user. ``show_favorites_bar`` Whether the specified user's favorites are shown as icons at the top of the profile page. ``show_favorites_tab`` Whether the specified user's favorites should be shown at all. ``statistics`` ``null`` if the specified user doesn't allow statistics to be shown or an object of statistics about the specified user. A user object resembles:: { "banned": false, "catchphrase": "", "commission_info": { "commissions": null, "details": "<", "price_classes": null, "requests": null, "trades": null }, "created_at": "2012-11-03T17:01:37Z", "featured_submission": null, "folders": [], "full_name": "weyk\u00ebnt", "login_name": "weykent", "media": { "avatar": [ { "mediaid": 937444, "url": "https://www.weasyl.com/static/user/66/42/8d/0a/3f/8c//5756/avatar.png" } ], "banner": [ { "mediaid": 937443, "url": "https://www.weasyl.com/static/user/66/42/8d/0a/3f/8c//5756/banner.gif" } ] }, "profile_text": "

yo. I do weasyl coding and shit.

😼

", "recent_submissions": [], "recent_type": "collections", "relationship": null, "show_favorites_bar": false, "show_favorites_tab": false, "statistics": { "faves_received": 0, "faves_sent": 2, "followed": 23, "following": 56, "journals": 0, "page_views": 16354, "submissions": 0, "submit_views": 0 }, "stream_text": "", "stream_url": "", "streaming_status": "stopped", "suspended": false, "user_info": { "age": null, "aim": "", "facebook": "", "foursquare": "", "gender": "h4x0r", "googleplus": "", "icq": "", "location": "seattle, wa", "msn": "", "myspace": "", "psn": "", "reddit": "", "skype": "", "steam": "", "tumblr": "", "twitter": "", "xboxlive": "", "yahoo": "", "youtube": "" }, "username": "weykent" } .. _media: Media keys ---------- *media* keys in Weasyl API responses take the form of a JSON object mapping descriptive names to media file objects. The media file objects will have at least two keys: *url*, and *mediaid*. The *mediaid* is a unique identifier which unambiguously refers to a particular file stored by Weasyl. The *url* is one possible URL where the file can be downloaded. There can be multiple possible *url*\ s for a given *mediaid*. A *mediaid* can also be ``null`` to indicate the *url* is already unambiguous. A media file object may also have another key: *links*. The *links* key is itself a media key, and allows media files to be linked to other media files. Currently, the only kind of link is ``"cover"``, which links a media file to its :term:`cover image`. For submissions, the possible descriptive names are ``"submission"`` for the original file uploaded by the user, ``"cover"`` for the submission's :term:`cover image`, and ``"thumbnail"`` for the submission's thumbnail. The ``"submission"`` and ``"cover"`` names are optional for a submission, while the ``"thumbnail"`` name will always exist. For users, the possible descriptive names are ``"avatar"`` for the user's avatar and ``"banner"`` for the user's banner. ``"banner"`` is optional while ``"avatar"`` will always exist. Here is an example of the media for a visual submission:: { "submission": [ { "links": { "cover": [ { "mediaid": 1651999, "url": "https://www.weasyl.com/static/media/..." } ] }, "mediaid": 1651999, "url": "https://www.weasyl.com/static/media/..." } ], "thumbnail": [ { "mediaid": 1652001, "url": "https://www.weasyl.com/static/media/..." } ], "cover": [ { "links": { "cover": [ { "mediaid": 1651999, "url": "https://www.weasyl.com/static/media/..." } ] }, "mediaid": 1651999, "url": "https://www.weasyl.com/static/media/..." } ] } .. _pagination: Pagination ---------- Pagination is done through *backid* and *nextid* (or, in some cases, *backtime* and *nexttime*) response keys and request query parameters. Paginated API endpoints will return JSON objects with *backid* and *nextid* keys to indicate how to find the previous and next pages of results. If *nextid* is not ``null``, there is a next page accessible by specifying that *nextid* as a query parameter, keeping all other query parameters the same. Similarly, if *backid* is not ``null``, there is a previous page accessible by specifying that *backid* as a query parameter. .. _authentication: Authentication -------------- Authentication can be done in one of two ways: a Weasyl API key, or an OAuth2 bearer token. Weasyl API keys are managed at , and are extremely simple to use. To authenticate a request, set the ``X-Weasyl-API-Key`` header to the value of an API key, and the user agent will be authenticated as the user who created the key. To authenticate a request with an OAuth2 bearer token, pass an ``Authorization: Bearer`` header along with the token, as described in . Errors ------ At the moment, these are the non-:http:statuscode:`200` statuses potentially emitted by the Weasyl API: - :http:statuscode:`401`. This is emitted for resources which require an :ref:`authenticated ` user if no authorization is provided, or if the provided authorization is invalid. - :http:statuscode:`403`. This is emitted in the case of an expected error. That is, Weasyl was able to process your request, but is unable to return the requested entity for some reason. - :http:statuscode:`404`. This is emitted if a URL is requested which doesn't have matching data. For example, a request to :http:get:`/api/users/(login_name)/gallery` for a :term:`login name` which doesn't exist. - :http:statuscode:`422`. This is emitted if a parameter's value is unparsable or invalid. For example, if a non-numeric value is specified for a parameter requiring a numeric value. - :http:statuscode:`500`. This is emitted in the case of an unexpected error. That is, Weasyl was unable to process your request. In addition to sending a non-:http:statuscode:`200` response, errors are signaled by returning a JSON object with an *error* key. The value of this key will be an object containing either a *code* key, a *name* key, or neither. An object with a *code* or *name* key will unambiguously specify the problem encountered. An object with neither key indicates that an unexpected error was encountered. An error response resembles the following:: { "error": { "name": "RatingExceeded" } } OAuth2 errors ~~~~~~~~~~~~~ If a bearer token has expired, the :http:header:`WWW-Authenticate` header in the response will include ``error="invalid_token"``. Glossary ======== .. glossary:: cover image The image displayed on the submission page, which may be smaller than the actual submission file. Cover images will be no larger than 1024 pixels by 3000 pixels. ISO 8601 timestamp A string representing a particular moment in time. Weasyl requires exactly one of the formats described by ISO 8601: ``YYYY-MM-DDTHH:MM:SSZ``. For example, ``2014-02-12T17:00:00Z``. As this includes a trailing ``Z``, the time is required to be in UTC. login name A user's username, lowercase, and omitting all non-alphanumeric, non-ASCII characters.