Skip to content

API v1

Jump to bottom
Ross Williams edited this page Jul 1, 2020 · 7 revisions

Setup

Create a wrapper for a given wiki and API version:

from scuttle import scuttle
API_KEY = "eyJ0eXAiOiJKV1QiLC(...)" # Personal Access Token

wiki = scuttle('en', API_KEY, 1)

The wiki here is 'en' and the API version is 1.

If you don't know the domain of your wiki:

print(scuttle(None, API_KEY, 1).wikis())

Find your wiki in the list.

Making requests

v1 of the API is tightly-scoped and you may have to make multiple requests in order to find the information you need.

For example, if you wanted to get the most recently-uploaded file from the page to which the user Croquembouche's most recent revision was applied:

wiki = scuttle('en', API_KEY, 1)
user_id = wiki.wikidotuser("Croquembouche")['wd_user_id']
revisions = wiki.wikidotuser_revisions(user_id, limit=1, direction='desc')
page_id = revisions[0]['page_id']
file_url = wiki.page_files(page_id)[0]['path']

Paginated methods

Some of SCUTTLE's methods are paginated. This means that each request returns only some of the data you need, and in order to get all the data, you will need to make a series of requests. From the API's wiki, these endpoints are the ones using the POST method.

Paginated methods offer the following keyword arguments:

  • limit: the number of items to be returned per page. Int between 1 and 100, default 20
  • offset: the number of items to skip. Int, default 0
  • direction: the direction that results should be ordered in, typically chronologically. Str of either "asc" or "desc", default "asc"

Paginated methods return more information than their non-paginated counterparts. For example, the non-paginated thread posts endpoint (wiki.thread_posts()) returns an unsorted list of posts in a thread with only their IDs and the ID of their parent posts. However, the paginated method returns an ordered list containing much more information, including the content of the posts. Imagine it like a book - the non-paginated method is the index of the book, telling you where to look to find information; whereas the paginated method is the rest of the book, with page after page of detailed information.

Paginated methods in this wrapper are denoted by the verbose attribute. Paginated versions of methods can be accessed by calling verbose (e.g. wiki.thread_posts.verbose()). For example:

page_id = wiki.page_by_slug("main")['id']
first_20_revisions = wiki.page_revisions.verbose(page_id)

List of methods

List all wikis:

wiki.wikis()

Get information about a given wiki

Clone this wiki locally