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
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
https://github.com/LLK/scratch-rest-api/wiki.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:
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!
Thank you!
Last edited by gdpr533f604550b2f20900645890 (March 3, 2016 01:03:42)
- DrKat123
- Scratcher
1000+ posts
The Scratch API
https://scratch.mit.edu/discuss/topic/185982/CSRF is Cross Site Request Forgery 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?
Thank you!
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:
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.
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:
- Posting content deliberately designed to crash the Scratch website or editor;
- Linking to pages containing viruses or malware;
- Using administrator passwords or pretending to be an administrator;
- Repeatedly posting the same material, or “spamming”;
- 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
Ohhh… It's to prevent CSRFs. Hence the “token” part of the name
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?
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):
After the Scratch servers get your request, they do some stuff on their side and serve an answer up:
Then you post a comment to the 1st user (wrgsfhwbxvb) of the site
The Scratch servers update the page with your comment, and then they send a confirmation message back to 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.
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.
- You kidnap Phasma.
- You force Phasma to disable shields.
- The Starkiller OS recognizes Phasma's login and trusts her. The OS complies and disables shields.
- 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
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 :-)
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:
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:
Easy!
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
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? 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!
- liam48D
- Scratcher
1000+ posts
The Scratch API
The buttons automatically do it.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? 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!
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
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. 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.
- Paddle2See
- Scratch Team
1000+ posts
The Scratch API
I would think that would be fine.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. 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
It's fineAm 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. 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.
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)
- 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.
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
Definitely an old topic, but I've got a relevant question:It looks like the variable “user” returns your username, but it doesn't work on the new pages
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.