API Reference - User

POST /v1/users Create a user

Create a new Pixela user.

Request Body

Key Type Description
token string [required] A token string used to authenticate as a user to be created. The token string is hashed and saved.
Validation rule: [ -~]{8,128}
username string [required] User name for this service.
Validation rule: [a-z][a-z0-9-]{1,32}
agreeTermsOfService string [required] Specify yes or no whether you agree to the terms of service.
Please see: Terms of service - Japanese version / Terms of service - English version
notMinor string [required] Specify yes or no as to whether you are not a minor or if you are a minor and you have the parental consent of using this service.

Example

$ curl -X POST https://pixe.la/v1/users -d '{"token":"thisissecret", "username":"a-know", "agreeTermsOfService":"yes", "notMinor":"yes"}' {"message":"Success.","isSuccess":true}

PUT /v1/users/<username> Update a user

Updates the authentication token for the specified user.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Request Body

Key Type Description
newToken string [required] It is a new authentication token. The token string is hashed and saved.
Validation rule: [ -~]{8,128}

Example

$ curl -X PUT https://pixe.la/v1/users/a-know -H 'X-USER-TOKEN:thisissecret' -d '{"newToken":"thisissecret"}' {"message":"Success.","isSuccess":true}

DELETE /v1/users/<username> Delete a user

Deletes the specified registered user.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Example

$ curl -X DELETE https://pixe.la/v1/users/a-know -H 'X-USER-TOKEN:thisissecret' {"message":"Success.","isSuccess":true}

API Reference - Graph

POST /v1/users/<username>/graphs Create a graph

Create a new pixelation graph definition.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Request Body

Key Type Description
id string [required] It is an ID for identifying the pixelation graph.
Validation rule: ^[a-z][a-z0-9-]{1,16}
name string [required] It is the name of the pixelation graph.
unit string [required] It is a unit of the quantity recorded in the pixelation graph. Ex. commit, kilogram, calory.
type string [required] It is the type of quantity to be handled in the graph. Only int or float are supported.
color string [required] Defines the display color of the pixel in the pixelation graph.
shibafu (green), momiji (red), sora (blue), ichou (yellow), ajisai (purple) and kuro (black) are supported as color kind.
timezone string [optional] Specify the timezone for handling this graph as Asia/Tokyo. If not specified, it is treated as UTC.
selfSufficient string [optional] If SVG graph with this field increment or decrement is referenced, Pixel of this graph itself will be incremented or decremented.
It is suitable when you want to record the PVs on a web page or site simultaneously.
The specification of increment or decrement is the same as Increment a Pixel and Decrement a Pixel with webhook.
If not specified, it is treated as none .

Example

$ curl -X POST https://pixe.la/v1/users/a-know/graphs -H 'X-USER-TOKEN:thisissecret' -d '{"id":"test-graph","name":"graph-name","unit":"commit","type":"int","color":"shibafu","timezone":"Asia/Tokyo"}' {"message":"Success.","isSuccess":true}

GET /v1/users/<username>/graphs Get graph definitions

Get all predefined pixelation graph definitions.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Example

$ curl -X GET https://pixe.la/v1/users/a-know/graphs -H 'X-USER-TOKEN:thisissecret' {"graphs":[{"id":"test-graph","name":"graph-name","unit":"commit","type":"int","color":"shibafu","timezone":"Asia/Tokyo","purgeCacheURLs":["https://camo.githubusercontent.com/xxx/xxxx","selfSufficient":"increment"]}]}

GET /v1/users/<username>/graphs/<graphID> Get a graph SVG

Based on the registered information, express the graph in SVG format diagram.

Query Parameter

Key Description  
date string [optional] If you specify it in yyyyMMdd format, will create a pixelation graph dating back to the past with that day as the start date.
If this parameter is not specified, the current date and time will be the start date.
(it is used timezone setting if Graph’s timezone is specified, if not specified, calculates it in UTC)
mode string [optional] Specify the graph display mode.
As of October 23, 2018, support only short mode for displaying only about 90 days.

Example

$ curl -X GET https://pixe.la/v1/users/a-know/graphs/test-graph?date=20180331&mode=short <svg xmlns="http://www.w3.org/2000/svg" width="220" height="135" ...

PUT /v1/users/<username>/graphs/<graphID> Update a graph

Update predefined pixelation graph definitions.
The items that can be updated are limited as compared with the pixelation graph definition creation.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Request Body

Key Type Description
name string [optional] It is the name of the pixelation graph.
unit string [optional] It is a unit of the quantity recorded in the pixelation graph. Ex. commit, kilogram, calory.
color string [optional] Defines the display color of the pixel in the pixelation graph.
shibafu (green), momiji (red), sora (blue), ichou (yellow), ajisai (purple) and kuro (black) are supported as color kind.
timezone string [optional] Specify the timezone for handling this graph as Asia/Tokyo. If not specified, it is treated as UTC.
purgeCacheURLs array[string] [optional] This is an advanced option.
Specify the URL to send the purge request to purge the cache when the graph is updated.
For example, in GitHub, since all images referenced from GitHub are cached, it is necessary to purge the cache every time the Pixeleation graph is changed.
Even with the same Pixelation graph, different cache URLs are generated when referring from multiple places, you can specify up to 5 URLs.
selfSufficient string [optional] If SVG graph with this field increment or decrement is referenced, Pixel of this graph itself will be incremented or decremented.
It is suitable when you want to record the PVs on a web page or site simultaneously.
The specification of increment or decrement is the same as Increment a Pixel and Decrement a Pixel with webhook.
If not specified, it is treated as none .

Example

$ curl -X PUT https://pixe.la/v1/users/a-know/graphs/test-graph -H 'X-USER-TOKEN:thisissecret' -d '{"name":"graph-name","unit":"commit","color":"shibafu","timezone":"Asia/Tokyo","purgeCacheURLs":["https://camo.githubusercontent.com/xxx/xxxx"]}' {"message":"Success.","isSuccess":true}

DELETE /v1/users/<username>/graphs/<graphID> Delete a graph

Delete the predefined pixelation graph definition.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Example

$ curl -X DELETE https://pixe.la/v1/users/a-know/graphs/test-graph -H 'X-USER-TOKEN:thisissecret' {"message":"Success.","isSuccess":true}

GET /v1/users/<username>/graphs/<graphID>.html View a graph detail

Displays the details of the graph in html format.

Example

$ open https://pixe.la/v1/users/a-know/graphs/test-graph.html

GET /v1/users/<username>/graphs/<graphID>/pixels Get graph pixels list

Get a Date list of Pixel registered in the graph specified by graphID.
You can specify a period with from and to parameters.

  • If you do not specify both from and to;
    • You will get a list of 365 days ago from today.
  • If you specify from only;
    • You will get a list of 365 days from from date.
  • If you specify to only;
    • You will get a list of 365 days ago from to date.
  • If you specify both from and to;
    • You will get a list you specify.
    • You can not specify a period greater than 365 days.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Query Parameter

Key Type Description
from string [optional] Specify the start position of the period.
to string [optional] Specify the end position of the period.

Example

$ curl -X GET https://pixe.la/v1/users/a-know/graphs/test-graph/pixels?from=20180101&to=20181231 -H 'X-USER-TOKEN:thisissecret' {"pixels":["20180101","20180331","20180402","20180505","20181204"}]}

API Reference - Pixel

POST /v1/users/<username>/graphs/<graphID> Post a Pixel

It records the quantity of the specified date as a “Pixel”.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Request Body

Key Type Description
date string [required] The date on which the quantity is to be recorded. It is specified in yyyyMMdd format.
quantity string [required] Specify the quantity to be registered on the specified date.
Validation rule: int^-?[0-9]+ float^-?[0-9]+.[0-9]+
optionalData string [optional] Additional information other than quantity. It is specified as JSON string.
The amount of this data must be less than 10 KB.

Example

$ curl -X POST https://pixe.la/v1/users/a-know/graphs/test-graph -H 'X-USER-TOKEN:thisissecret' -d '{"date":"20180915","quantity":"5","optionalData":"{\"key\":\"value\"}"}' {"message":"Success.","isSuccess":true}

GET /v1/users/<username>/graphs/<graphID>/<yyyyMMdd> Get a Pixel

Get registered quantity as “Pixel”.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Example

$ curl -X GET https://pixe.la/v1/users/a-know/graphs/test-graph/20180915 -H 'X-USER-TOKEN:thisissecret' {"quantity":"5","optionalData":"{\"key\":\"value\"}"}

PUT /v1/users/<username>/graphs/<graphID>/<yyyyMMdd> Update a Pixel

Update the quantity already registered as a “Pixel”. If target “Pixel” not exist, create a new “Pixel” and set quantity.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Request Body

Key Type Description
quantity string [optional] Specify the quantity to be registered on the specified date.
Validation rule: int^-?[0-9]+ float^-?[0-9]+.[0-9]+
optionalData string [optional] Additional information other than quantity. It is specified as JSON string.
The amount of this data must be less than 10 KB.

Example

$ curl -X PUT https://pixe.la/v1/users/a-know/graphs/test-graph/20180915 -H 'X-USER-TOKEN:thisissecret' -d '{"quantity":"7","optionalData":"{\"key\":\"value\"}"}' {"message":"Success.","isSuccess":true}

PUT /v1/users/<username>/graphs/<graphID>/increment Increment a Pixel

Increment quantity “Pixel” of the day (it is used “timezone” setting if Graph’s “timezone” is specified, if not specified, calculates it in “UTC”).
If the graph type is int then 1 added, and for float then 0.01 added.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.
Content-Length Since the request body is not specified, specify the Content-Length header.

Example

$ curl -X PUT https://pixe.la/v1/users/a-know/graphs/test-graph/increment -H 'X-USER-TOKEN:thisissecret' -H 'Content-Length:0' {"message":"Success.","isSuccess":true}

PUT /v1/users/<username>/graphs/<graphID>/decrement Decrement a Pixel

Decrement quantity “Pixel” of the day (it is used “timezone” setting if Graph’s “timezone” is specified, if not specified, calculates it in “UTC”).
If the graph type is int then -1 added, and for float then -0.01 added.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.
Content-Length Since the request body is not specified, specify the Content-Length header.

Example

$ curl -X PUT https://pixe.la/v1/users/a-know/graphs/test-graph/decrement -H 'X-USER-TOKEN:thisissecret' -H 'Content-Length:0' {"message":"Success.","isSuccess":true}

DELETE /v1/users/<username>/graphs/<graphID>/<yyyyMMdd> Delete a Pixel

Delete the registered “Pixel”.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Example

$ curl -X DELETE https://pixe.la/v1/users/a-know/graphs/test-graph/20180915 -H 'X-USER-TOKEN:thisissecret' {"message":"Success.","isSuccess":true}

API Reference - Webhook

POST /v1/users/<username>/webhooks Create a webhook

Create a new Webhook.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Request Body

Key Type Description
graphID string [required] Specify the target graph as an ID.
type string [required] Specify the behavior when this Webhook is invoked.
Only increment or decrement are supported.

Example

$ curl -X POST https://pixe.la/v1/users/a-know/webhooks -H 'X-USER-TOKEN:thisissecret' -d '{"graphID":"test-graph","type":"increment"}' {"webhookHash":"<WebhookHashString>","message":"Success.","isSuccess":true}

GET /v1/users/<username>/webhooks Get webhooks

Get all predefined webhooks definitions.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Example

$ curl -X GET https://pixe.la/v1/users/a-know/webhooks -H 'X-USER-TOKEN:thisissecret' {"webhooks":[{"webhookHash":"<WebhookHashString>","graphID":"test-graph","type":"increment"}]}

POST /v1/users/<username>/webhooks/<webhookHash> Invoke webhooks

Invoke the webhook registered in advance.
It is used “timezone” setting as post date if Graph’s “timezone” is specified, if not specified, calculates it in “UTC”.

Request Header

Key Description
Content-Length Since the request body is not specified, specify the Content-Length header.

Example

$ curl -X POST https://pixe.la/v1/users/a-know/webhooks/<webhookHash> -H 'Content-Length:0' {"message":"Success.","isSuccess":true}

DELETE /v1/users/<username>/webhooks/<webhookHash> Delete a webhook

Delete the registered Webhook.

Request Header

Key Description
X-USER-TOKEN [required] It is the authentication token specified at the time of user registration.

Example

$ curl -X DELETE https://pixe.la/v1/users/a-know/webhooks/<webhookHash> -H 'X-USER-TOKEN:thisissecret' {"message":"Success.","isSuccess":true}