IPaste SDK v.1.0

www.iPaste.eu SDK / Web Service documentation 2013/06/27 v.1.0
2013/07/26
1
IPASTE SDK
iPaste is the tool for storing public and password protected pastes on the web (www.iPaste.eu). It is a
product aimed mostly for developers, because it allows to collaborate with other people without the need
of a git (for medium and large projects, of course, it is recommended to use a git  ) or share quickly a
textual file over the web.
Feel free to contact me for any bugs you will find or any questions and suggestions.
WHAT IS A “PASTE”?
A paste is a code snippet (but it could be a simple text snippet) which has some properties:
Property Description
id identification number
title paste title
description short description of the paste
content paste content
status could be hidden, if you don’t want to make paste accessible directly by users (but it will
be accessible by direct link), so that it will not be visible in the Explorer page and the web
service will not give it’s ID if someone queries it, or visible, which means that everyone
can access to the paste and view it in the Explore page
password allows you to protect your paste. Guests or registered users will not be able to access to
your paste though they make a request using the iPaste SDK. In fact only the paste owner
or who knows the password can get access to the paste content
source the website where you took the code snippet
tags words that describes shortly the paste. These words will appear to the footer of paste,
clicking on one of them, the user will be redirected to the iPaste search engine
expiry date every paste has an expiration date, after that it will be removed
syntax paste syntax, the code snippet programming language
colour paste background colour in the Explore page
Some of this properties are required, like paste title and content. The identification number is essential
when you make a paste update.

2013/07/26
2
GETTING STARTED
I wrote quickly two libraries to communicate with the web service, one intended to be used by PHP
developers and the other one for Java developers. Both libraries are very similar in structure, but surely
they differ a bit (I want to remind that java is strongly typed).
Download the iPaste Java SDK: https://github.com/iPasteEu/ipaste-sdk-java
Or the iPaste PHP SDK: https://github.com/iPasteEu/ipaste-sdk-php
SDK Documentations are too boring? Go to the code sample now:
Java: https://github.com/iPasteEu/ipaste-sdk-java/tree/master/iPasteAPI/src/com/ipaste/samples
PHP: https://github.com/iPasteEu/ipaste-sdk-php/tree/master/samples
PHP
SKD
The PHP SDK consists in one large PHP file that encloses all classes and interfaces. The most
important class, that you have to know, is IPaste, which implements iPasteICore interface
and is used to communicate with iPaste.
JAVA
SDK
The equivalent of the PHP IPaste class, in the Java SDK, is the com.ipaste.core.IPaste class
that implements com.ipaste.core.IPasteCore interface. You will use the IPaste class to
communicate with iPaste platform. Every public function will throw an IPasteException.
For now, only the following functions are available in both PHP IPaste and Java IPaste classes:
Function Description
login() Makes a login, giving the developer key, username and password, and returns a
temporary key which is the session id
paste() Stores a new paste on the iPaste platform
update() Updates an existing paste on the iPaste platform. Requires the paste id.
remove() Removes the paste whit the paste id given as parameter.
getUserPastes() Returns all logged in user paste IDs or all public pastes of another username, which
is passed as parameter.
get() Retrieves a paste (it could be public or, if the logged in user is the owner, private)
in a specified format (JSON, TEXT, YAML, HTML)
If you want to make a request to the iPaste web service, you should make a POST request to this link:
http://www.ipaste.eu/api
If you make a GET request to this link without passing parameters, it will return the iPaste SDK
documentation.

2013/07/26
3
Instantiate IPaste class
PHP
SDK
First of all we need to instantiate the IPaste class. This constructor accepts three values: the
developer key, user’s username and user’s password. You can get your developer key from
your iPaste profile (you have to be registered to get your developer key). The developer key
is a hashed string which allows iPaste to identify you. The username and the password could
be your log in information or of another iPaste user. The constructor will automatically try
to make a login. You can instantiate the IPaste class without the need of passing values,
setting them in a later time through the getter and setter functions. Be aware that without
these three information you will not be able to use the other functions.
$ipaste = new iPaste(DEVE_KEY, USERNAME, PASSWORD);
$ipaste = new iPaste(“8g3addbb98d7f8e373feb1b6c3ab263k”, “test”,”test”);
JAVA
SDK
There are three constructors that could be used to instantiate the IPaste class. Everyone
of them will throw the IPasteException if it will be encountered problems.
The first one is an empty constructor, it will throw an exception if the constant DEV_KEY is
null. In fact it will try to assign the DEV_KEY value to the instance variable named devKey .
The DEV_KEY have to be initialized with your developer key witch you can get from your
user profile (it is available only for registered users).
The second constructor requires user’s username and password. It calls the empty
constructor to retrieve the developer key, so that if you do not initialize the DEV_KEY
constant, it will throw an exception. This constructor will try to login to iPaste.
It is recommended to use the third constructor, which requires also the developer key.
Like the previous one, after checking the input, it will try to login to the iPaste platform.
Class IPaste implements IPasteCore{ … private final static String DEV_KEY = “my_developer_key”; … }
IPaste ipaste = new IPaste();
Class IPaste implements IPasteCore{ … private final static String DEV_KEY = “my_developer_key”; … }
IPaste ipaste = new IPaste(“Username”, “Password”);
IPaste ipaste = new IPaste(“my_developer_key”, “Username”, “password”);
REQUEST DETAILS
URI Parameter Required Description
See the login request details
RESPONSE: see the login request details
GET Request example
See the login request details
ERROR MESSAGE RESPONSES
 See the login request details

2013/07/26
4
Login function
IPaste platform needs a logged in user and a valid developer key in order to fulfil the client’s request. The
login function requires a valid developer key, which you can get from your iPaste profile, a username and a
password. Password and the username converted to upper case will be hashed before they will be send to
the iPaste platform. If no error occurs, the function returns a temporary key that corresponds to the
session id.
PHP
SKD
The login function has three parameters, none of them are required (perhaps the
developer key, username and password were initialized in the constructor and the
constructor called the login function). The function converts the username to upper case
and the hashes it before the request. In addition, the function hashes the password. This
function will validate the input values and then it will try to make a login.
$ipaste = new iPaste();
$tmpKey = $ipaste->login(DEVE_KEY, USERNAME, PASSWORD);
JAVA
SKD
Login is an overloading method. The first method accepts a developer key, a username
and a password. The second method is an empty method because it retrieves the login
information from the class variable instances. The method converts username to upper
case and then hashes the username and password. After that, it merges the developer key
with username and password and sends them to the iPaste platform.
IPaste ipaste = null;
try {ipaste = new IPaste();} catch (IPasteException e) {}
try {String tmpKey = ipaste.login(DEV_KEY, “Username”,”Password”)); } catch (IPasteException e) {}
REQUEST DETAILS
act YES Request action. Set it to login in order to make a login request.
a YES Consists in three hashed values appended together: md5(developer
key)md5(uppercase(username))md5(password)
RESPONSE: [tmpKey] || error message
GET Request example
http://www.ipaste.eu/api?act=login&a=863adcbb98d7f8e3f3eeb1b6c3ab263c526bdc7513421a9626f71b4dad2503230cc12b16c
c10b0484a31e15f1feb2de1
 “KO - Invalid login data” – you should hash username and password if you don’t use the iPaste SDK
 "KO - Invalid Developer key"
 "KO - Invalid username"
 "KO - Invalid password"
 “KO - Invalid username or password”
 “KO - Invalid developer key”
 “KO - internal error (ref. user)” – contact iPaste support
 “KO - user account was blocked or deleted”
 “KO - internal error (ref. developer)” - contact iPaste support
 “KO - developer account was blocked or deleted”

2013/07/26
5
Paste function
Paste function allows storing a paste. In order to be able to store a paste on the iPaste platform it is
necessary to own a tmpKey, which you can retrieve through the login request. As I mentioned previously, a
paste must have a value for the title and the content, because these information are required. The paste
password must be hashed before sending it to the iPaste platform.
PHP
SDK
The paste function accepts two parameters, one of which is not required. The first is the
paste that is an instance of the iPastePaste class. The second is the tmpKey, which is
optional, because perhaps it was generated by the login function and stored in a private
instance class variable. Function validates both, paste and the tmpKey (if the input tmpKey
is not null) before the paste insertion. Function could throw an iPasteException if error
occurs. Some paste fields accepts only specified values, so that you can use the
appropriate interface (the valid colour values you can find them in the iPasteIValidColours,
or the valid paste statuses in iPasteIValidStatuses, or the valid expiry dates in the
iPasteIValidExpiryDates and finally the valid syntaxes in the iPasteIValidSyntaxes). If no
error occurs, this function will return the paste id.
try {
/************************************************************************************/
$myPaste = new iPastePaste(null, "iPastetWebServiceIntegrationTest", "Short description", "This is a
paste sample!!!'", iPasteIValidStatuses::HIDDEN, "this is a PASSWORD ", "http://www.site.com", "tag1,
tag2, tag3", iPasteIValidExpiryDates::ONE_MONTH, iPasteIValidSyntaxes::TEXT,
iPasteIValidColours::BLUE);
$response = $ipaste->paste($myPaste, $tmpKey);
$response = $ipaste->paste($myPaste);
/************************************************************************************/
$myShortPaste = new iPastePaste(null, "iPastetWebServiceIntegrationTest", null, "This is a paste
sample!!!'");
$response = $ipaste->paste($myShortPaste, $tmpKey);
$response = $ipaste->paste($myShortPaste);
/************************************************************************************/
} catch (iPasteException $e) {}
JAVA
SKD
In the java SDK we have two methods, one accepts a paste and a tmpKey and the other
one accepts only the paste. If you made a login using one of the logins methods, you have
not to be worried about the tmpkey, because it is setted automatically after the login
operation and retrieved by the paste method. The method that accepts the tmpKey as
parameter will call the other one paste method. Some paste fields accepts specified
values, so that you can use the appropriate interface to get the correct value (for status
use PasteValidStatuses, for expiryDate use PasteValidExpiryDates, for syntaxes use
PasteValidSyntaxes and for colours PasteValidColours).Both, the tmpKey and the paste
will be validated, if an error occurs, it will be thrown an IPasteException. If no error
occurs, the method will return the paste id (integer).
try {int ret = ipaste.paste(new Paste("Title Title Title", "Description Description Description Description",
"content content contentcontent content content content", PasteValidStatuses.HIDDEN, "this is a PASSWORD",
"https://www.ipaste.eu", "tags, tags, tags, tag, stags", PasteValidExpiryDates.ONE_HUNDRED_YEARS,
PasteValidSyntaxes.TEXT, PasteValidColours.RED));
/************************************************************************************/
int ret = ipaste.paste(new Paste("Title", "Description nDescription", "content ncontent"));
}catch(IPasteException e){}

2013/07/26
6
REQUEST DETAILS
act YES Request action. Set it to insert in order to post a
new paste.
a YES Is the tmpKey that was returned by the login
request (session ID)
pasteTitle YES Paste title
pasteDescription NOT Paste description
pasteContent YES Paste content
pasteStatus NOT Paste status (hidden or visible)
c NOT Paste hashed password (MD5)
pasteSource NOT Paste source (URI)
pasteTags NOT Paste tags separated by commas
pasteExpiryDate NOT Paste expiration date (see the valid values in iPaste
SDK)
pasteSyntax NOT Paste syntax (see the valid values in the iPaste
SDK)
pasteColour NOT Paste colour (see the valid values in the iPaste
SDK)
RESPONSE: [paste id] || error message
GET Request example
act=insert&a=ppqbmeph95dbd293fo7ghfmt96&pasteTitle=Title+Title+Title&pasteDescription=Description+Description+Descripti
on+Description&pasteContent=content+content+contentcontent+content+content+content&pasteStatus=hidden&c=e4948f69ad
1b37f16f7d84734975cc13&pasteSource=https%3A%2F%2Fwww.ipaste.eu&pasteTags=tags+tags+tags+tagstags&pasteExpiryDa
te=100+YEAR&pasteSyntax=text&pasteColour=red
 “KO - Invalid paste ID”
 “KO - Invalid temporary key”
 “KO - Internal error (ref. paste)”
 “KO - Invalid paste title”
 “KO - Invalid paste content”
 “KO - Internal error (ref. account)”
 “KO - You have published too many pastes for today”
 “KO - Internal error when trying to store paste (re. storage)”
 “KO - Internal error (ref. developers account)”
 “KO - Paste ID required”
 “KO - Paste title required”
 “KO - Paste content required”

2013/07/26
7
Update function
Allows to update an existing paste owned by the logged in user. In order to be able to store a paste on the
iPaste platform it is necessary to own a tmpKey, which you can retrieve through the login request. The new
paste that will replace the other one stored on the iPaste platform must have an identification number
which allows to identify the paste that the server will update, a title and a content. The paste password
must be hashed before sending it to the iPaste platform.
PHP
SDK
The update functions accepts two parameters, one of which is not required. The first is the
paste that has to replace the other paste stored on the iPaste platform, it is an instance of
the iPastePaste class. The second is the tmpKey, which is optional, because perhaps it was
generated by the login function and stored in a private instance class variable. Function
validates both, paste and the tmpKey (if the input tmpKey is not null) before the paste
update. Function could throw an iPasteException if error occurs. Some paste fields accepts
only specified values, so that you can use the appropriate interface (the valid colour values
you can find them in the iPasteIValidColours, or the valid paste statuses in
iPasteIValidStatuses, or the valid expiry dates in the iPasteIValidExpiryDates and finally the
valid syntaxes in the iPasteIValidSyntaxes). If no error occurs, this function will return TRUE.
try {
/*************************************************************************************
*****/
$myPaste = new iPastePaste(1000, "iPastetWebServiceIntegrationTest", "Short description", "This is a
paste sample!!!'", iPasteIValidStatuses::HIDDEN, "this is a PASSWORD ", "http://www.site.com", "tag1,
tag2, tag3", iPasteIValidExpiryDates::ONE_MONTH, iPasteIValidSyntaxes::TEXT,
iPasteIValidColours::BLUE);
$response = $ipaste->update ($myPaste, $tmpKey);
$response = $ipaste->update ($myPaste);
/*************************************************************************************
*****/
$myShortPaste = new iPastePaste(1000, "iPastetWebServiceIntegrationTest", null, "This is a paste
sample!!!'");
$response = $ipaste->update ($myShortPaste, $tmpKey);
$response = $ipaste->update ($myShortPaste);
/*************************************************************************************
*****/
} catch (iPasteException $e) {}
JAVA
SDK
In java we have two methods, one accepts a paste and a tmpKey and the other one
accepts only the paste. If you made a login using one of the logins methods, you have not
to be worried about the tmpkey, because it is setted automatically after the login
operation and retrieved by the update() method. Some paste fields accepts specified
values, so that you can use the appropriate interface to get the correct value (for status
use PasteValidStatuses, for expiryDate use PasteValidExpiryDates, for syntaxes use
PasteValidSyntaxes and for colours PasteValidColours). The method that accepts the
tmpKey as parameter will call the other one update() method. Both, the tmpKey and the
paste will be validated, if an error occurs, it will be thrown an IPasteException. If no error
occurs, the method will return true (boolean).
String tmpKey = “”;

2013/07/26
8
Paste paste = new Paste(1000, "Title Title Title", "Description Description Description Description", "content
content contentcontent content content content", PasteValidStatuses.HIDDEN, "this is a PASSWORD",
"https://www.ipaste.eu", "tags, tags, tags, tag, stags", PasteValidExpiryDates.ONE_HUNDRED_YEARS,
PasteValidSyntaxes.TEXT, PasteValidColours.RED);
try {int ret = ipaste.update (paste, tmpKey);} catch (IPasteException e) {}
try {int ret = ipaste.update (paste);} catch (IPasteException e) {}
paste = new Paste("Title", "Description nDescription", "content ncontent");
try{ int ret = ipaste.update (paste, tmpKey); }catch(IPasteException e){}
try{ int ret = ipaste.update (paste); }catch(IPasteException e){}
REQUEST DETAILS
act YES Request action. Set it to update in order to post a
new paste.
a YES Is the tmpKey that was returned by the login
request (session ID)
id YES Paste id of the paste that you want to update
pasteTitle YES Paste title
pasteDescription NOT Paste description
pasteContent YES Paste content
pasteStatus NOT Paste status (hidden or visible)
c NOT Paste hashed password (MD5)
pasteSource NOT Paste source (URI)
pasteTags NOT Paste tags separated by commas
pasteExpiryDate NOT Paste expiration date (see the valid values in iPaste
SDK)
pasteSyntax NOT Paste syntax (see the valid values in the iPaste
SDK)
pasteColour NOT Paste colour (see the valid values in the iPaste
SDK)
RESPONSE: [paste id] || error message
GET Request example
act=update&a=rq5ac183llct89bijv5rnikb53&id=3952&pasteTitle=BBBB+Title+Title&pasteDescription=BBBB+Description+Descript
ion+Description&pasteContent=BBBB+content+contentcontent+content+content+content&pasteStatus=hidden&c=cb0a6616285
723d1f97a5af20d2ae860&pasteSource=https%3A%2F%2Fwww.ipasteBBBB.eu&pasteTags=BBBB+tags+tags+tagstags&pasteExp
iryDate=1+MONTH&pasteSyntax=teraterm&pasteColour=red
 “KO - Internal error (ref. paste)”
 “KO - Invalid paste title”
 “KO - Invalid paste content”
 “KO - Internal error (ref. account)”
 “KO - You have published too many pastes for today”
 “KO - Internal error when trying to store paste (re. storage)”
 “KO - Internal error (ref. developers account)”
 “KO - Paste title required”
 “KO - Paste content required”

2013/07/26
9
Remove function
Removes a paste according to the paste id passed as parameter. The logged in user has to be the paste
owner in order to be able to remove the specific paste. A tmpKey is required, which is your session id, to
remove the paste.
PHP
SDK
The function has two parameters: the pasteId and the tmpKey (that is optional if the login
function was never called). The pasteId is the paste identification number. The logged in
user has to be the paste owner in order to be able to proceed with the paste deletion.
The tmpKey corresponds to the session id. The functions returns true (boolean) if no error
occurs, otherwise it will throw an iPasteException. If you call this function on a removed
paste, it will return always true.
try { $response = $ipaste->remove(3872); } catch (iPasteException $e) {}
JAVA
SDK
There are two methods. The first has one parameter, the pasteId, which is the paste
identification number. Only the paste owner can remove his paste. The second method
has a further parameter, the tmpKey, which is optional if the login method was never
called. The tmpKey corresponds to the session id. The method return true if no error
occurs, otherwise it will throw an IPasteException. If you call this method on a removed
paste, it will return always true.
try { boolean res = ipaste.remove(1000); } catch (IPasteException e) {}
REQUEST DETAILS
act YES Request action. Set it to remove in order to make a remove request.
a YES Is the temporary key returned by the login request
id YES The paste identification number that you want to remove
RESPONSE: [OK] || error message
GET Request example
http://www.ipaste.eu/api?act=remove&a=ppqbmeph95dbd293fo7ghfmt96&id=3997
 “KO - Invalid paste ID”
 "KO - Unauthorized action" – you are not the paste owner
 “KO – Invalid tmpKey”

2013/07/26
10
GetUserPastes function
Returns a list of public and hidden paste IDs of the logged in user. You can also specify a username and the
server will return a list constituted by the user’s public paste IDs. By specifying a format, you be able to
change server response format.
PHP
SDK
The function has no required parameters. The default response format is JSON, but you can
change it to the TEXT or CVS format. Each row in the TEXT format ends with the rn
characters. The response format does not influence the function output. In fact, the
function will always return an array of strings. A return format could be one of the constant
values stored in the iPasteIResponseListFormat.
try {$response = implode(“, ”, $ipaste->getUserPastes(iPasteIResponseListFormat::JSON));} catch
(iPasteException $e) {}
JAVA
SDK
We have four methods in java that allow retrieving the list of paste IDs of the logged in
user or of a specified user. The first method is none parameterized method. The server
will return the list of public and hidden pastes of the current logged in user. The second
method accepts a response format; the full list of response formats is stored in the
IPasteExtraResponseFormat interface. The third method accepts also a username. The
server will return all public paste IDs of the specified user.
try {ipaste.getUserPastes(IPasteResponseFormat.CVS, "testt");} catch (IPasteException e1) {}
try {ipaste.getUserPastes(IPasteResponseFormat.CVS);} catch (IPasteException e1) {}
REQUEST DETAILS
act YES Request action. Set it to get_all_user_pastes in order to get all user’s
paste IDs.
frm NOT The response format (valid formats are text, cvs, json). The server
will respond in the text format if this field is not defined.
uid NOT User’s username of whom you want to retrieve the list of paste IDs.
Leave it blank to get the logged in user paste IDs list.
RESPONSE: [list of paste IDs according to the frm value format] || error message
GET Request example
http://www.ipaste.eu/api?act=get_all_user_pastes&frm=json&a=ppqbmeph95dbd293fo7ghfmt96
 “KO - Please login first”
 "KO – Invalid username“
 “KO - Internal error (ref. dev. account)”
 “KO - invalid output format”
 “KO – Invalid tmpKey”
 “KO - Internal error”

2013/07/26
11
Get
Retrieves a paste according to the paste id given as parameter. You can get a paste in different formats:
TEXT, JSON, YAML, HTML and XML. A tmpKey is necessary in order to get a public/ hidden or password
protected pastes. I want to remind you that the tmpKey is the session id.
PHP
SDK
The get function accepts three values: the pasteId (required), the response format which
is not required (see iPasteIResponsePasteFormat for valid formats) and the tmpKey
(optional). If no error occurs it will return the requested paste, otherwise an
iPasteException will be thrown.
try {response = $ipaste->get(1000, iPasteIResponsePasteFormat::HTML); } catch (iPasteException $e) {}
JAVA
SDK
There are three methods, the most overloaded method accepts three values: the pasteId
of which we want to get the content, the response format (look at
IPasteExtraResponseFormat for valid values) and finally the tmpKey. The get method
return a String value.
try {String str = ipaste.get(3943, IPasteExtraResponseFormat.YAML));} catch (IPasteException e) {}
try {String str = ipaste.get(3943, IPasteExtraResponseFormat.HTML));} catch (IPasteException e) {}
try {String str = ipaste.get(3943, IPasteExtraResponseFormat.CML));} catch (IPasteException e) {}
try {String str = ipaste.get(3943, IPasteExtraResponseFormat.JSON);} catch (IPasteException e) {}
try {String str = ipaste.get(3943, IPasteExtraResponseFormat.TEXT));} catch (IPasteException e) {}
REQUEST DETAILS
act YES Request action. Set it to get in order to get a paste.
frm NOT Response format (could be text, json, yaml, html and xml). The
default format is text.
id YES Paste identification number.
RESPONSE: [paste in the specified format by frm] || error message
GET Request example
act=get&a=ppqbmeph95dbd293fo7ghfmt96&id=3943&frm=html
 “KO - You must login first”
 “KO - Invalid paste id”
 “KO - Invalid response format”
 “KO - The paste you have requested does not exists”
 “KO - The paste is password protected”

IPaste SDK v.1.0

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Viewers also liked

Viewers also liked (20)

Similar to IPaste SDK v.1.0

Similar to IPaste SDK v.1.0 (20)

Recently uploaded

Recently uploaded (20)

IPaste SDK v.1.0