-
Notifications
You must be signed in to change notification settings - Fork 0
API Version 2
State: stable, obsolete
The previous stable API version that you should not develope for anymore. However, still using it is fine.
Besides a call to create a user, which is protected by an API key, all calls must be authenticated. This can happen in one of three* ways:
1.) HTTP Basic Auth Headers. This is the currently preferred method until I have decided which way the authentication should go. It is important to invest in using SSL since HTTP Basic Auth headers do NOT provide encryption!
2.) Calling GET /v2/user/token with HTTP Basic Auth Headers set. This will return a token that can be used instead of the credentials. You will then need to set X-Pasty-Token as HTTP header instead of HTTP Basic Auth. But you are strongly encouraged to leave your finger off of this, as it may vanish in upcoming version.
3.) There is also a legacy method of setting X-Pasty-User and X-Pasty-Password. But you are strongly encouraged to leave your finger off of this, as it may vanish in upcoming version.
In addition to setting the appropriate HTTP Status Code, so usually 2xx, in case of errors 4xx or 5xx, the API server will generally reply with a JSON object with the following fields:
Field-Key: code
Optional: No
Content: HTTP Status Code, 2xx indicating that everything went as expected.
Content-Type: Integer
Description: This field will be in every normal response from Pasty server, indicating the general state of your request. Usually 200 or 201 if everything went as expected. Everything else indicates usually an error. For example 401 would indicate that authentication was not successful, 500 would indicate a problem on the server, 400 a problem in your request (like wrong parameters)
Field-Key: payload
Optional: Yes
Content: A JSON object containing the actual payload, if you requested data from the server.
Content-Type: Object
Description: Any response can contain a payload object, that will contain the actual data you requested from the server. See "Payload Response" for details.
Field-Key: error
Optional: Yes
Content: A JSON object containing information about the error that occured.
Content-Type: Object
Description: If an error occurs, the Pasty server will add an Object called "error" to the response. This Object will contain informations regardings the error that occured. For details see the "Error Response" section.
A Payload Response is, when the Pasty server sends data to the client, usually because the client requested data from the server. This means, that Payload Responses are a usual case, when requesting via HTTP GET. The Payload Response is an JSON object.
Which fields or objects can be part of an Payload Response is different for each request and hence documented in the request section.
An Error Response happens when something about the request did not work, whether this error took place on server side or client side. Please note that not all errors that can occur will lead to an Error Response. For example a server crash or a network problem will most likely result in a time-out.
The following fields are part of the Error Response, which is a JSON object:
Field-Key: code_http
Optional: No
Content: HTTP Status Code that represents the error that happened.
Content-Type: Int
Description: For example 401 indicates that authentication was not successful, 500 would indicate a problem on the server, 400 a problem in your request (like wrong parameters). This is just a broad general HTTP Status Error-Code. More specific error codes can be found in the code_pasty field.
Field-Key: code_pasty
Optional: Yes
Content: If availabe, a more detailed error code as the HTTP Status Code.
Content-Type: Int
Description: This helps when deciding, what error message to present to your user. For example, HTTP Status Code 401 could mean that the provided username / password were wrong, or that a token is expired.
Field-Key: message
Optional: Yes
Content: If availabe, a default error message for the error that occured. Currently in english only.
Content-Type: String
Description: Provides a default error message. You are encouraged to overwrite this message with a localized version.
The Clipboard consists of a collection of Items. It can be accessed using HTTP GET on
URL: /v2/clipboard/list.{format}
Parameters: {format} being the output format you want. Currently only JSON (.json) is supported. In time, at least XML will also be offered. If you do not specify a format, you will receive JSON.
Sample output:
{
"code": 200,
"payload": {
"items": [
{"item": "sdsfd", "_id": "4fa4ee1b7cdd42230e000003"},
{"item": "asdasd", "_id": "4fa4ee197cdd42230e000002"},
{"item": "1", "_id": "4f927e924bf6e71b170001f0"},
{"item": "2", "_id": "4f927e914bf6e71b170001ed"},
{"item": "3", "_id": "4f927e914bf6e71b170001ec"},
{"item": "4", "_id": "4f927e914bf6e71b170001ea"}
]
}
}Possible Error Codes:
...
##Items Items can be accessed as a subcategory of the Clipboard.
URL: GET /v2/clipboard/item/{id}
Parameters: {id} being the Object Id of the Item (Obtained by getting the Clipboard)
Sample output:
{
"code": 200,
"payload": {
"item": "http://www.reddit.com/",
"_id": "4f927e914bf6e71b170001ea"
}
}Possible Error Codes:
...
###Creating a new Item
URL POST /v2/clipboard/item/
Parameters: You need to supply the Item content using a HTTP body with JSON: { "item": "thestringtoadd" }
Sample output: Will send you the Object Id of the newly created item.
{
"code": 200,
"payload": {
"_id": "4f927e914bf6e71b170001ea" }
}Possible Error Codes:
...
###Deleting an Item
URL: DELETE /v2/clipboard/item/{id}
Parameters: {id} being the Object Id of the Item (Obtained by getting the Clipboard)
Sample output: { "code": 200 }
Possible Error Codes:
...
Creating users is currently only allowed for certain clients, to enforce acceptance of ToS and Privacy Policy. Once I figured out how to solve this problem, it might become public.
However, updating and deleting users is allowed under the limitations and conditions below.
All writing user related actions need to be authenticated using the HTTP Basic method. A token will not be enough here.
###Requesting a Token to replace the users credentials
URL: GET /v2/user/token
Parameters: Necessarily username and password via HTTP Basic Auth
Sample output: Gives you the token, the user name and user id, and a timestamp in unix seconds when the token will expire.
{
"code": 200,
"payload":
{
"token":"b229454a89ab6366cee93ad9838d8412bf54aa057de48c2cfb8be88c8051ae3160e8f802db2530d865e5f3972dad754db423ea3892458b32513f73564026f800",
"user": "test",
"uid": "4f8dasgc2305893a0e000001",
"expires": 13362540171
}
}Possible Error Codes:
...
###Checking validity of a User Token
URL: GET /v2/user/token/validity
Parameters: X-Pasty-Token HTTP Header
Sample output: Will tell you if a token is valid (HTTP Status Code 200 and a payload) or not (HTTP Status Code 401).
{
"code": 200,
"payload": {
"expires": 13362540171
}
}Possible Error Codes:
...
###Getting user information
URL: GET /v2/user/{id}
Parameters: {id} being the users id. If {id} is ommitted, the authenticated users information will be delivered.
Sample output:
{
"code": 200,
"payload": {
"user": "username",
"uid": "4f8dasgc2305893a0e000001"
}
}Possible Error Codes:
...
###Creating a new user
URL: POST /v2/user/
Parameters: API Key that allows to add users. Currently not public. Calling this will hopefully always result in a 401 error.
If you have one, you need to send username and password as JSON HTTP body:
{ "user": "yourusername", "password": "yourpassword" }
Sample output:
{
"code": 401,
"error":
{
"http_code":401,
"message":"API key is invalid"
}
}Possible Error Codes:
...
###Updating a user password
URL: PUT /v2/user/{id}
Parameters:
- {id} being the users id.
- Send the new password as JSON HTTP body:
{ "newPassword": "yournewpassword" }
Sample output: { "code": 200 }
Possible Error Codes:
...
###Deleting a user
URL: DELETE /v2/user/{id}
Parameters: {id} being the users id.
Sample output: { "code": 200 }
Possible Error Codes:
...
This sections covers general queries regarding the server, not users, clipboards or items.
URL: GET /v2/server/version
Parameters: none
Sample output:
{
code: 200,
payload: {
code: 29,
name: '0.2.0 master'
}
}Possible Error Codes:
- Unexpected errors (Open Issue!)