This document was written by @kiansjet, but since he is a basic user he cant post anything in tutorials, so he has asked me to do this for him. ~ DisneyDreams123
All questions/comments should go towards @kiansjet.
Introduction
I was pretty much on Pastebin one day and I had a thought:
Nobody seems to have made a tutorial on how this website’s web API works despite how much devs I know use it… kcool I’ll do it.
Enough about me. You’re here to figure out how to use Pastebin’s API from Roblox!
"Whats a Pastebin?"
Great question! Pastebin is a website on which 99% of the users have a simple goal:
I have some code/text/ideas that I want to share with a friend/co-worker/community. I’ll just paste it here and link them to the paste!
it’s a very simplistic site with a very simplistic goal.
K. So how do I use this Web API?
You’re full of great questions, aren’t you?
Note: If you feel like I have left anything out in the following few paragraphs, see if you can find the answer on Pastebin’s API page, and make sure to let me know so I can add it.
Prequesites
First of all, the most important key to interaction with the Pastebin web API is a developer API Key. Note that this key itself is not used to post pastes on the website. Rather, it is used for metrics and rate limiting. Your unique key will be shown to you on this page, provided you are signed in.
Note: If you are signed in with an account created using any of the “Sign in with (service)” buttons, go to the change password page, and make a password for your account, as you need it later in the tutorial.
Turn HttpService on while you’re at it.
Getting to dat programming I - Setup
Let’s make a new script and start writing in it, shall we?
First of all let’s define some simple functions and variables that will make our code shorter in the long run:
local http = game:GetService('HttpService')
local urlEncode = function(str) return http:UrlEncode(str) end -- Will be used to encode our data later on
local GET = function(url) return http:GetAsync(url) end
local POST = function(url,data) return http:PostAsync(url,data,'ApplicationUrlEncoded') end
local DevKey = -- Paste your API key here as a STRING
local UserKey -- Leave this one blank, we'll talk about it in a bit :P
local PostUrl -- Leave this blank as well. We'll also talk about this in a bit
local DefaultUrl = 'https://pastebin.com/'
Now that we have the most basic stuff out of the way, let’s talk about the UserKey.
On Pastebin, users are allowed to paste stuff without needing to be logged in.
As mentioned earlier, the DevKey you will be providing to the API will not be used to identify your account on pastes you make. Now, I can hear some of you asking:
But Kian, what if I do want a paste I make to have my name on it?
That, my friend, is where your UserKey comes in. Your UserKey is used to identify you as the account that wrote the paste. A UserKey is required to be passed to the API if you want to:
- Delete a paste made with the same
UserKey - Make a private paste
- Fetch a paste that only the user the
UserKeyrepresents has access to
Sounds good! How do I get one?
Getting to dat programming II - First POST
To get one, we will have to make our first API request, which is conveniently the easiest to make. First of all though, I have to introduce you all to a method of sending POST data to a webpage, ApplicationUrlEncoded.
Let’s say I want to send 2 variables to https://google.com, varA and varB. Let’s break this communication down:
-- We won't use the previously defined POST() function for this example
http:PostAsync(
'https://google.com', -- The URL we want to send the data to
'varA='..urlEncode(varA)..'&varB='..urlEncode(varB), -- Our data that will be encoded in the URL
'HttpUrlEncoded' -- Declaring the format in which our data is in
)
As shown in our example, the ApplicationUrlEncoded format is simply a long string of variable declarations separated by & signs (except the first variable). Take note that I am running urlEncode() on all the arguments, because it is imperative that “Dangerous characters” stay out of our final URL.
Tom Scott explains this pretty well from 3:00 to 3:38 in this video:
So, with that explanation out of the way, let’s add a few more lines to our open script:
do -- Container so any irrelevant variables dont leak
-- Define the URL we want to send the login request to
local url = 'https://pastebin.com/api/api_login.php' -- URL given to us from Pastebin's API page
local username = -- Type your username here
local password = -- Type your password here
-- On the following line, we will compile all the required variables into a single string (They do not have to be listed in a particular order)
local data = 'api_dev_key='..urlEncode(DevKey)..'&api_user_name='..urlEncode(username)..'&api_user_password='..urlEncode(password)
UserKey = POST(url,data)
end
WHAT ARE YOU DOING NOT WRAPPING THAT IN A PCALL ARE YOU CRAZY?
Calm down. I reluctantly have to agree with him though. In a realistic scenario, you probably want to wrap this in a pcall and properly handle any errors. But for the sake of this tutorial, we will only be covering API errors returned from Pastebin’s side, which I will cover at the end.
Getting to dat programming III - New Paste
Well? I have everything I need to make a paste. NOW will you tell me how?
Sure. You’ve earned it. To make a new paste, a lot of parameters are required, at least in comparison to the single POST we have done so far.
Method URL: https://pastebin.com/api/api_post.php
A paste’s required parameters are:
-
api_dev_key- Your DevKey -
api_paste_code- The body of the paste - A variable called
api_optionthat we will set to'paste'
A paste’s optional parameters are:
-
api_user_key- Your UserKey (If not provided, cannot be pasted as private and will show author as:Guest) -
api_paste_name- The title of the paste (internally capped at 60 characters) | Defaults to'Untitled' -
api_paste_format- The syntax highlighting of your paste | Defaults to'' (None) -
api_paste_private- The privacy setting of your paste (0 = Public | 1 = Unlisted | 2 = Private) | Defaults to0 -
api_paste_expire_date- The expiration time for your paste | Examples here | Defaults to'N'
With that in mind, let’s write some more code to make a short string show up on Pastebin. The API should return a url to the paste if we are successful. Lets write that to our PostUrl variable.
do -- Another container
-- Define the URL we want to send the paste to
local url = 'https://pastebin.com/api/api_post.php' -- URL given to us from Pastebin's API page
-- For the sake of this tutorial, we will define everything for the following paste
local code = 'Wassup Jimbo' -- Not stealing memes | This will be our body
local name = 'while true do print("oof") end' -- Not stealing memes | This will be our title
local format = 'lua' -- Contextual highlighting for our glorious code
local privacy = '0' -- We want the world to see our meme | Make sure this is a STRING
local expiration = 'N' -- N for never gonna give you up
-- On the following line, we will compile all the required variables into a single string (They do not have to be listed in a particular order)
local data = 'api_option=paste&api_dev_key='..urlEncode(DevKey)..'&api_user_key='..urlEncode(UserKey)..'&api_paste_name='..urlEncode(name)..'&api_paste_code='..urlEncode(code)..'&api_paste_format='..urlEncode(format)..'&api_paste_private='..urlEncode(privacy)..'&api_paste_expire_date='..urlEncode(expiration)
PostUrl = string.sub(POST(url,data),#DefaultUrl) -- We only need the PostId, not the full URL that the API returns
end
Getting to dat programming IV - Fetching Pastes
Alright… What if I want to fetch a raw copy of a paste from Pastebin?
There’s actually 2 distinct methods of fetching a raw paste from Pastebin. Lets go over both.
Method 1 - GET from page
This method involves less code as it is a GET, not a POST, and therefore does not need any of that api stuff we sent it. This is actually the only method in this tutorial that doesn’t require an API or User Key to invoke.
Method URL: 'https://pastebin.com/raw/
This method is just a simple 4 lines of code:
do
local url = 'https://pastebin.com/raw/'
print(GET(url..PostUrl)) -- We'll print the resulting raw, which should be 'Wassup Jimbo'
end
Method 2 - POST through API
As the heading suggests, this method utilizes the pastebin web API.
Method URL: https://pastebin.com/api/api_raw.php
This method involves a little more code and requires the following parameters:
-
api_dev_key- This should be obvious by now -
api_user_key- Yes. This is required. You can use this method to fetch private pastes by the same user -
api_paste_key- We will use ourPostUrlvariable -
api_option- We will set this to'show_paste'
You should be used to the formatting of our code so far, so here’s a sample:
do -- Container
-- Define the URL we want to send the API request to
local url = 'https://pastebin.com/api/api_raw.php' -- URL given to us from Pastebin's API page
-- On the following line, we will compile all the required variables into a single string (They do not have to be listed in a particular order)
local data = 'api_option=show_paste&api_dev_key='..urlEncode(DevKey)..'&api_user_key='..urlEncode(UserKey)..'&api_paste_key='..urlEncode(PostUrl)
print(POST(url,data)) -- We'll print the resulting raw, which should be 'Wassup Jimbo'
end
Getting to dat programming V - Deleting Pastes
What if I want to delete a paste I just made?
As long as you created that paste with the same UserKey, you can delete the paste as well.
Method URL: https://pastebin.com/api/api_post.php
(Yes, this is the same URL as posting, but we are going to change a key variable)
Deleting a paste requires the following parameters:
-
api_dev_key- Of course it does -
api_user_key- How else is it going to know you are the author? -
api_paste_key- Same key format as earlier (PostUrl) -
api_option- This time, we will set this to'delete'
Here’s some sample code:
do -- Another container
-- Define the URL we want to send the paste to
local url = 'https://pastebin.com/api/api_post.php' -- URL given to us from Pastebin's API page
-- On the following line, we will compile all the required variables into a single string (They do not have to be listed in a particular order)
local data = 'api_option=delete&api_dev_key='..urlEncode(DevKey)..'&api_user_key='..urlEncode(UserKey)..'&api_paste_key='..urlEncode(PostUrl)
print(POST(url,data)) -- If successful, should print 'Paste Removed'
end
Handling API Errors
Over the course of this tutorial so far, I have assumed that all the data you provide to pastebin.com is always valid, and that none of you will encounter API errors. That’s stupidly unrealistic, so here is how you should handle any errors that fly your way:
(This is clearly not the only method, but its one that I think will suffice.)
Create a filter function
Create a function like the following to filter your web responses:
local errString = 'Bad API request'
local function filter(str)
if string.sub(str,1,#errString) == errString then
return false,str
end
return true,str
end
With this function, the first returned value is whether the string provided is a suspected error, and the second value is always the original string. All of Pastebin’s API errors will always begin with the provided errString, so detecting them should be a breeze.
Hold on a second. Doesn’t that mean that if I try to fetch a paste that starts with that
errString, the response will be falsely flagged?
Yes, unfortunately. I do not have a solution to that problem ¯\ _ (ツ) _ /¯
Welp. After working on this at crawling speed for the past 3 hours, I am exhausted. I hope you all get as much of a kick out of this as I do. Bye!
Feedback is appreciated, it will help improve my personal knowledge and others, thank you.
