Pen.io API (beta)
INTRODUCTION
The Pen.io API allows developers to build applications that can make use of the Pen.io Network. As well as standard functions such as creating, editing and deleting Pen.io pages, through the API, developers can use Pen.io as a powerful private key store. The API uses standard REST practices.
AUTHENTICATION
To use the Pen.io API, you must have a key. An API key can be generated on this page
Authentication is done using HTTP Basic Authorization and all calls to the API must include your Key in a request header.
Generate an API Key
Example
curl -i -H "api-key: YOURAPIKEYGOESHERE" -X HEAD
CREATE NEW PAGE
POST http://pen.io/pages/
Response Codes
- 201 Location: http://YOURPAGENAME.pen.io - page created
- 409 (conflict) - page name is not available
- 412 (precondition failed) - fields validation error, error messages are in the response body
Parameters (POST body):
- page_name (required) - Name of the page
- password (required) - Password with a length between 1 and 30 characters
- title (optional) - Page title. Length between 1-255. HTML is allowed.
- content (optional) - Page content. HTML is allowed.
- private (optional) - Privacy flag (to use Pen.io as key store). 0 or 1. If 1, created page will be available only through API with basic authorization
Example:
curl -i -H "api-key: YOURAPIKEYGOESHERE" -X POST -d "page_name=pagetitlegoeshere&password=password&private=0" \
http://pen.io/pages
Update page content
PUT http://pen.io/pages/name/
Response codes:
- 204 - page modified
- 301 - Location: http://name.page.io/ - page modified, page name has been changed
- 409 (conflict) - new page name is not available
- 412 (precondition failed) - fields validation error
- 401 - authorisation required
- 403 - unauthorized access
- 404 - page does not exist
Paramters:
url-encoded name=value pairs, all parameters are optional, but at least one pair should be presented. If a parameter is missed in the request, it will not be changed:
- page_name - Name of the page. Length between 2 and 60
- title - Page Title. Length between 1 and 255. HTML is allowed
- content - Page Content. HTML is allowed
- private - Privacy Flag. 0 or 1. If 1, page will only be accessible through API
Example:
curl -i -H "api-key: YOURAPIKEYGOESHERE" -X PUT -d "title=Here is a New Title&content=Some New Content&private=1" /
http://resttestpage:password@pen.io/pages/resttestpage
Check page availability:
HEAD http://pen.io/pages/name
response codes:
- 200 - OK (page name is taken)
- 404 - page does not exist (page name is available)
Example:
curl -i -H "api-key: YOURAPIKEYGOESHERE" -X HEAD http://pen.io/pages/resttestpage
Get Page in HTML Format:
GET http://pen.io/pages/name
Response Codes:
- 200 - OK
- 404 - page does not exist
- 401 - authorization required
- 403 - unauthorized access
Example:
curl -i -H "api-key: YOURAPIKEYGOESHERE" http://resttestpage:password@pen.io/pages/resttestpage
Get Page in JSON Format:
GET http://pen.io/pages/name/json
Response Codes:
- 200 - OK
- 404 - page does not exist
- 401 - authorization required
- 403 - unauthorized access
Example:
curl -i -H "api-key: YOURAPIKEYGOESHERE" http://resttestpage:password@pen.io/pages/resttestpage/json
Get Page in XML Format:
GET http://pen.io/pages/name/xml
Response Codes:
- 200 - OK
- 404 - page does not exist
- 401 - authorization required
- 403 - unauthorized access
Example:
curl -i -H "api-key: YOURAPIKEYGOESHERE" http://resttestpage:password@pen.io/pages/resttestpage/xml
Delete a Page:
DELETE http://pen.io/pages/name
Response Codes:
- 204 - OK
- 404 - page does not exist
- 401 - authorization required
- 403 - unauthorized access (wrong password)
Example:
curl -i -H "api-key: YOURAPIKEYGOESHERE" -X DELETE http://resttestpage:password@pen.io/pages/resttestpage