itchy-api docs

This is the official documentation for the itchy-api project, which is an incomplete wrapper for the Scratch API that runs on Vercel's Serverless Functions. You can view the project on GitHub here. We're open for contributions, so feel free to fork the repository and make a pull request! Many thanks to towerofnix/scratch-api-unofficial-docs for some object definitions.

GET /api/explore

Returns an array of project objects.

Query params:

• mode - method to sort, options of popular, trending, and recent. Defaults to popular
• offset - see Limits and Offsets docs. Defaults to 0
• tag - return only projects with a specific tag, value can be any string. Defaults to undefined

GET /api/frontpage

Returns an array of project objects.

Query params:

• page required - section of the Front Page to grab, values of featured, toploved, topremixed, sds, curated, and recent. Defaults to undefined

GET /api/project

Returns a single project object OR a standard comment object, depending on the value of the comments parameter.

Query params:

• id required - the project ID to retrieve. Defaults to undefined
• comments - whether or not to grab comments from a project, value must be a boolean. Defaults to false
• offset - only applicable if the comments parameter is true. See Limits and Offsets docs. Defaults to 0

GET /api/user

Returns a single user object OR a non-standard comment object, depending on the value of the comments parameter.

Query params:

• user required - the username to retrieve. Defaults to undefined
• comments - whether or not to grab comments from a user, value must be a boolean. Defaults to false
• offset - only applicable if the comments parameter is true. See Limits and Offsets docs. Defaults to 0

GET /api/search

Returns a single Qwant search object.

Query params:

• q required - the query to search. Defaults to undefined

GET /api/csrf

Returns a single csrf token from the API.

GET /api/image

Returns an object containing a data value (the base64 data of an image) and a requested value (the original requested URL).

Query params:

• url required - the image url. Defaults to undefined

POST /api/auth

Returns a session object. This requires the body header to be set (for security reasons) instead of easier query parameters.

Example body header:

  {
    "username": "mycoolusername",
    "password": "$uper_secr3t-password"
  }

Non-standard comment object

The non-standard comment object was created because user and studio comments still run on the depreciated site-api interface that returns comments as HTML. The itchy-api wrapper compiles that HTML into custom JSON objects and returns that instead. A non-standard comment object looks like this:

  {
    "id": "12345678",
    "author": {
      "username": "griffpatch",
      "image": "//scratch.mit.edu/griffpatch.png",
  }
    "content": "hello",
    "timestamp": "2020-12-20t22:17:06z",
    "replies": [
        {
            "id": "12345679",
            "author": {
                "username": "will_wam",
                "image": "//scratch.mit.edu/will_wam.png"
            "content": "@griffpatch what is up",
            "timestamp": "2020-12-20t22:37:38z"
        }
    ]
  }
      

To-do

While itchy-api is largely functional for now, there is still much to work on:

• Replace non-standard comment objects with ones that match Scratch
• Add studio endpoints
• Add POST-based endpoints
• Add authentication utilities done