Discuss Scratch

bobbybee
Scratcher
1000+ posts

The Scratch API

Hello Scratchers!

So you want to learn how to be a Scratch API ninja? Are you in awe by the Scratch project that lets you comment on the actual website? Curious who the 10,000,000th Scratcher is? Maybe you just want to follow Kaj? Scratch's APIs are at the heart of this.

What is an API, you ask? It stands for “Application Programming Interface,” although that isn't particularly helpful. Facilemente, el API es el manero en que una programa puede communicar con una otra… le API de Scratch te permette d'utiliser Scratch avec ton propre logiciel!

Oh, wait, you wanted the answer in English. Simply put, a program's API is a fancy way of saying the way it communicates with other programs in a system. Within Scratch, the Scratch APIs are the way that your browser communicates with the Scratch database, or that the editor creates a cloud variable. Except the nice thing about Scratch's API in particular is that it is (mostly) open and documented. Your programs can communicate with Scratch using its API.

Okay, awesome, there's this magical black box controlled by pixie dust that allows you to use fairies to make Scratchical magic. Seriously though, show me some code!

Here is, first of all, the wizard's spellbook; written by the Scratch Team, it should be your first go-to spot for using the API: https://github.com/LLK/scratch-rest-api/wiki .

Question: How do I actually use the thing?

Short answer: Make a REST request to the listed endpoint with the listed arguments.

Long answer: Scratch's main site uses a RESTful API– more programmer jargon, I know. It basically means that it uses a special subset of the web to piggyback its API on. Try clicking the follow link: https://api.scratch.mit.edu/users/mres/following Hint, hint, that's an API request!

To actually make this REST request is done the same way as any other web request. I don't know what language you want to code in – JavaScript and Python tend to be popular around here – but just look up “get request” or “post request”, and I'm sure you'll find plenty of results. The documentation for the specific endpoint (URL basically) will tell you which one.

Question: I'm confused. Walk me through it please?

Short answer: That wasn't a question. Try again.

Long answer: Say you want to do something with users. You find https://github.com/LLK/scratch-rest-api/wiki/Users documenting the way to do this. At the top, it says “GET”. It's a GET request, okay? What about “/users/:username”? That's the endpoint. It means, “replace ‘:username’ with the username you want, and then you have a web URL”. Wait, where's the URL? At the Scratch API, of course! Prepend all your requests with the API server, api.scratch.mit.edu. And that's your request. https://api.scratch.mit.edu/users/mres. The result will be coded in JSON, which is a fancy way of encoding information in a computer. Just decode it (search “decode JSON yourlanguagehere”) and it'll behave like you'd expect in your language of choice.

Question: I'm still confused.

Short answer: That's still not a question. Ask it below, and maybe a kind soul here will answer.

Please only discuss the API and API-related matters in this topic to avoid cluttering the forums :-)

Thanks!
~bobbybee

Last edited by bobbybee (March 3, 2016 01:03:12)


“Ooo, can I call you Señorita Bee?” ~Chibi-Matoran
WooHooBoy
Scratcher
1000+ posts

The Scratch API

bobbybee wrote:

Here is, first of all, the wizard's spellbook; written by the Scratch Team, it should be your first go-to spot for using the API: https://github.com/LLK/scratch-rest-api/wiki.

gives a 404 because of the period.

Other than that, great guide!

considered harmful
gdpr533f604550b2f20900645890
Scratcher
1000+ posts

The Scratch API

Excuse me, but I wrote some scripts, and they seem to be broken. Others don't know why, and thing that it has something to do with the “CSRF token.” Could someone please check out the problem? https://scratch.mit.edu/discuss/topic/185982/

Thank you!

Last edited by gdpr533f604550b2f20900645890 (March 3, 2016 01:03:42)

DrKat123
Scratcher
1000+ posts

The Scratch API

Chibi-Matoran wrote:

Excuse me, but I wrote some scripts, and they seem to be broken. Others don't know why, and thing that it has something to do with the “CSRF token.” Could someone please check out the problem? https://scratch.mit.edu/discuss/topic/185982/

Thank you!
CSRF is Cross Site Request Forgery
Waaat

Moving from Scratch? Don't learn C or Java, try Snap!
it haz OOP
DrKat McKatFace
First of all I'm 100% human and humans does not have a cat face
and second, the Boaty McBoatFace/Parsey McParseFace madness has just begun

λ
Sharp, my new Scratch mod
Is my post/siggy worthy for an internet?
Firedrake969
Scratcher
1000+ posts

The Scratch API

It's to prevent CSRFs. Hence the “token” part of the name

'17 rickoid

bf97b44a7fbd33db070f6ade2b7dc549
gdpr533f604550b2f20900645890
Scratcher
1000+ posts

The Scratch API

So, am I not able to run code despite being on the Scratch website, concerning my own account?
Jonathan50
Scratcher
1000+ posts

The Scratch API

Cool tutorial/thing.

Last edited by Jonathan50 (March 3, 2016 03:13:51)


Not yet a Knight of the Mu Calculus.
Paddle2See
Scratch Team
1000+ posts

The Scratch API

This is a good tutorial! But remember, “With great power, comes great responsibility”. We've had a number of cases of Scratchers abusing the API to spam the site in various ways. Perhaps it would be a good idea to add a section in the first post about ethical uses of the API, with reference specifically to section 3.5 of the Terms of Use:

3.5 You agree not to use Scratch in any way intended to disrupt the service, gain unauthorized access to the service, or interfere with any other user's ability to use the service. Prohibited activities include, but are not limited to:
  1. Posting content deliberately designed to crash the Scratch website or editor;
  2. Linking to pages containing viruses or malware;
  3. Using administrator passwords or pretending to be an administrator;
  4. Repeatedly posting the same material, or “spamming”;
  5. Using alternate accounts or organizing voting groups to manipulate site statistics, such as purposely trying to get on the “What the Community is Loving/Remixing” rows of the front page.

Note that scripting to follow large numbers of Scratchers, posting comments to large numbers of Scratchers, adding tons of projects to a studio, etc., is considered spamming and a misuse of system resources.

Scratch Team Member, kayak and pickleball enthusiast, cat caregiver.

This is my forum signature! On a forum post, it is okay for Scratchers to advertise in their forum signature. The signature is the stuff that shows up below the horizontal line on the post. It will show up on every post I make.
(credit to Za-Chary)



;
DrKat123
Scratcher
1000+ posts

The Scratch API

Firedrake969 wrote:

It's to prevent CSRFs. Hence the “token” part of the name
Ohhh…

Moving from Scratch? Don't learn C or Java, try Snap!
it haz OOP
DrKat McKatFace
First of all I'm 100% human and humans does not have a cat face
and second, the Boaty McBoatFace/Parsey McParseFace madness has just begun

λ
Sharp, my new Scratch mod
Is my post/siggy worthy for an internet?
iamunknown2
Scratcher
1000+ posts

The Scratch API

OK, for anyone who's still baffled with what an API is:

As @bobbybee has said, API stands for “Application Programming Interface”. Still confused? Don't worry!

Let's say you want to write this awesome program that posts messages of congratulation to the 1st, 10th, 100th, 1000th and 10000th user. You're set, happily writing the code, until you run into a problem: How are you going to find the 1st Scratch post to them within your program?
Your program --- ? --- Scratch site

Since your program relies on getting information from Scratch, you have to connect with Scratch in some sort of way. The problem: You can't by just getting information from the source code

Oh noes! Your simple script will now be impossible!

Fortunately, there is a pre-made system that will give you that data easily. You make your program send a GET request to the Scratch servers (the computers that are responsible for serving the site to users):
Your program >> REQUEST FOR USER 1 OF SITE >> Scratch servers

After the Scratch servers get your request, they do some stuff on their side and serve an answer up:
Scratch servers >> USER 1 OF SITE IS wrgsfhwbxvb >> Your program

Then you post a comment to the 1st user (wrgsfhwbxvb) of the site
Your program >> REQUEST FOR POSTING COMMENT "Congratulations for being 1st user of site" TO USER wrgsfhwbxvb >> Scratch servers

The Scratch servers update the page with your comment, and then they send a confirmation message back to your program:
Scratch servers >> YOUR REQUEST WAS CARRIED OUT SUCCESSFULLY >> Your program

Update: CSRF tokens

Now, some of you might've tried running

In your error messages, you probably see a mention about a CSRF token.

As other Scratchers have said already, CSRF stands for Cross Site Request Forgery. It's a bad thing. There's an easy way to explain it:
Let's say you're Finn from Star Wars VII and you're trying to break into the Starkiller.

  1. You kidnap Phasma.
  2. You force Phasma to disable shields.
  3. The Starkiller OS recognizes Phasma's login and trusts her. The OS complies and disables shields.
  4. Starkiller Base goes boom boom.

Last edited by iamunknown2 (March 3, 2016 13:13:00)


| My website | Using Geany | A Christian | Running Ubuntu MATE 14.04 with Flash 18.0 (release 0) | Search this with quotation marks on Google to view my posts: “ellipsepostpianolizard” (some posts may not show up) |

Moving on from Scratch? Learn Python/a scripting language (e.g Perl, JavaScript), then move on to a C derivative
bobbybee
Scratcher
1000+ posts

The Scratch API

@Paddle2See, iamunknown2

I'll look over your posts in more detail and revise mine when I have a lot more time / focus tonight. Thanks for your input :-)

“Ooo, can I call you Señorita Bee?” ~Chibi-Matoran
liam48D
Scratcher
1000+ posts

The Scratch API

Lots of requests require a CSRF token. That's the little token your browser and Scratch share that lets you do lots of things on Scratch, especially things that will in any way interact with the community.

When you log in, a cookie gets assigned to you. Part of it lists your CSRF token. Here's an example of response cookies from /account/login:
scratchsessionsid=[very very very long string]
scratchcsrftoken=[not so long string]

Those are the two tokens you'll need to use the site or interact with the API. Remember, if you get a CSRF validation error, all you need to do is modify your HTTP request:
X-CSRFToken: [scratchcsrftoken cookie]

Easy!

202e-202e-202e-202e-202e UNI-CODE~~~~~
gdpr533f604550b2f20900645890
Scratcher
1000+ posts

The Scratch API

liam48D wrote:

Lots of requests require a CSRF token. That's the little token your browser and Scratch share that lets you do lots of things on Scratch, especially things that will in any way interact with the community.

When you log in, a cookie gets assigned to you. Part of it lists your CSRF token. Here's an example of response cookies from /account/login:
scratchsessionsid=[very very very long string]
scratchcsrftoken=[not so long string]

Those are the two tokens you'll need to use the site or interact with the API. Remember, if you get a CSRF validation error, all you need to do is modify your HTTP request:
X-CSRFToken: [scratchcsrftoken cookie]

Easy!
How do I do that? Why does my code not run, even though I use it when logged in, and can send the same requests through manually clicking buttons?
liam48D
Scratcher
1000+ posts

The Scratch API

Chibi-Matoran wrote:

liam48D wrote:

Lots of requests require a CSRF token. That's the little token your browser and Scratch share that lets you do lots of things on Scratch, especially things that will in any way interact with the community.

When you log in, a cookie gets assigned to you. Part of it lists your CSRF token. Here's an example of response cookies from /account/login:
scratchsessionsid=[very very very long string]
scratchcsrftoken=[not so long string]

Those are the two tokens you'll need to use the site or interact with the API. Remember, if you get a CSRF validation error, all you need to do is modify your HTTP request:
X-CSRFToken: [scratchcsrftoken cookie]

Easy!
How do I do that? Why does my code not run, even though I use it when logged in, and can send the same requests through manually clicking buttons?
The buttons automatically do it.

In JavaScript:
// get CSRF token
var csrfToken = document.cookie.match(/scratchcsrftoken=([^;]+)/)[1];
// set xhr header, assume we already have an XMLHttpRequest that has not yet
// been sent (but I think it has to be opened first)
xhr.setRequestHeader('X-CSRFToken', csrfToken);
// now we can send it or do other things
...
xhr.send();

This is just off the top of my head but I think that's how it works

202e-202e-202e-202e-202e UNI-CODE~~~~~
gdpr533f604550b2f20900645890
Scratcher
1000+ posts

The Scratch API

Paddle2See wrote:

Note that scripting to follow large numbers of Scratchers, posting comments to large numbers of Scratchers, adding tons of projects to a studio, etc., is considered spamming and a misuse of system resources.
Am I allowed to attempt to mass-unfollow people or mass-unfavorite projects, considering that API request time limits are followed? I'm trying to do that.
Paddle2See
Scratch Team
1000+ posts

The Scratch API

Chibi-Matoran wrote:

Paddle2See wrote:

Note that scripting to follow large numbers of Scratchers, posting comments to large numbers of Scratchers, adding tons of projects to a studio, etc., is considered spamming and a misuse of system resources.
Am I allowed to attempt to mass-unfollow people or mass-unfavorite projects, considering that API request time limits are followed? I'm trying to do that.
I would think that would be fine.

Scratch Team Member, kayak and pickleball enthusiast, cat caregiver.

This is my forum signature! On a forum post, it is okay for Scratchers to advertise in their forum signature. The signature is the stuff that shows up below the horizontal line on the post. It will show up on every post I make.
(credit to Za-Chary)



;
DrKat123
Scratcher
1000+ posts

The Scratch API

Chibi-Matoran wrote:

Paddle2See wrote:

Note that scripting to follow large numbers of Scratchers, posting comments to large numbers of Scratchers, adding tons of projects to a studio, etc., is considered spamming and a misuse of system resources.
Am I allowed to attempt to mass-unfollow people or mass-unfavorite projects, considering that API request time limits are followed? I'm trying to do that.
It's fine
For a nice API interface you can use Dylan5957's ScratchAPI interface

Moving from Scratch? Don't learn C or Java, try Snap!
it haz OOP
DrKat McKatFace
First of all I'm 100% human and humans does not have a cat face
and second, the Boaty McBoatFace/Parsey McParseFace madness has just begun

λ
Sharp, my new Scratch mod
Is my post/siggy worthy for an internet?
Gaza101
Scratcher
500+ posts

The Scratch API

If you want to include it in the post, I have recently updated the wiki page on the Scratch API.

Last edited by Gaza101 (March 14, 2016 14:20:36)


Gaza101: retired member of the Scratch 2.0 Transition Team


PullJosh
Scratcher
1000+ posts

The Scratch API

Definitely an old topic, but I've got a relevant question:

Is it possible, using the API, to find the username of the person who is currently logged in? I want to create a page where, using JS, I can grab some information specific to the user without needing them to type their username.

I feel like this was a thing at one point but I can no longer find it.
NickyNouse
Scratcher
1000+ posts

The Scratch API

PullJosh wrote:

Definitely an old topic, but I've got a relevant question:

Is it possible, using the API, to find the username of the person who is currently logged in? I want to create a page where, using JS, I can grab some information specific to the user without needing them to type their username.

I feel like this was a thing at one point but I can no longer find it.
It looks like the variable “user” returns your username, but it doesn't work on the new pages

Powered by DjangoBB