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 (<Wrapper>.thread_posts(thread_id)) 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; the paginated method is the rest of the book, with page after page of detailed information.

Accessing paginated methods

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

page_id = wiki.page_by_slug("main")['id']
first_20_revisions = wiki.page_revisions.verbose(page_id, limit=20)
first_revision = first_20_revisions[0]

Note that some paginated methods do not have a non-paginated counterpart (e.g. POST /forum/{id}/since/{timestamp}). These methods will raise an error if you try to use their non-paginated method - always use the paginated method instead (<Wrapper>.forum_threads_since.verbose(forum_id, timestamp)).

Iterating through a paginated method

To iterate through all pages of a paginated method, you could write a loop that increments the offset parameter by the limit and then makes the new request. Or, you could let the wrapper do that work for you.

A call to <Wrapper>.verbose with the method you'd like to iterate and any arguments will return a generator that iterates over all pages of the paginated method. For example:

thread_posts_generator = wiki.verbose(wiki.thread_posts, thread_id, limit=20)
for posts in generator:
    print(len(posts))  # 20

Note that even though we're going to be iterating over the paginated version of the method, <Wrapper>.verbose has been called with the non-paginated version (<Wrapper>.thread_posts). This is to save space and avoid having to write "verbose" twice.

Also note that the length of the returned 'page' will be equal to the specified limit, until you reach the end of the data. The final 'page' will likely contain fewer elements than the limit.

List of methods

List all wikis:

wiki.wikis()

Get information about a given wiki

Clone this wiki locally