Repository navigation
PyAcct API v2
Welcome to the API documentation! On this page, we will detail the REST API used to access the PyAcct v2 release.
This is the "login" endpoint. With a passed username and password, PyAcct will check if the password submitted is a match for the stored password of the user with the matching username. If so, a status of 200 will be returned, as well as an access token in the form of a string UUID. Otherwise, an error status of 401 will be returned.
HTTP method: POST
Endpoint path: /pyacct/2/session/
Content type: application/json
Authorization: None
Input data:
{
"username" : "account_username",
"password" : "account_password"
}Output data:
{
"access_token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"token_type": "bearer"
}This endpoint is used to create a new account. By passing a username and a password, a new account will be created with that username and password. An error status of 400 will be returned if the username submitted is already taken, or if the passwords submitted do not match. Otherwise, this should return an status of 200.
HTTP method: POST
Endpoint path: /pyacct/2/account/
Content type: application/json
Authorization: None
Input data:
{
"username" : "account_username",
"password" : "account_password",
"password_confirmation" : "account_password",
"attributes" : [
{"key" : "key1", "value" : "value1"},
{"key" : "key2", "value" : "value2"},
{"key" : "key3", "value" : "value3"}
]
}Output data: null
Given a session token, this endpoint allows for the retrieval of the account ID and username. If you are extending this service, you should use the returned ID for your join tables as it does not change if the username is changed, and as such, this allows you to use the same session token for controlled access.
HTTP method: GET
Endpoint path: /pyacct/2/account/
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Input data: null
Output data:
{
"id": -1,
"username": "account_username"
}Given a session token, this endpoint allows for the retrieval of the account ID and username. If you are extending this service, you should use the returned ID for your join tables as it does not change if the username is changed, and as such, this allows you to use the same session token for controlled access. This will return a 401 status error if the user is not authenticated.
HTTP method: GET
Endpoint path: /pyacct/2/account/{username}
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'This is required to prevent abuse. Accounts are required to be authenticated in order to query other accounts.
Input data: null
Output data:
{
"id": -1,
"username": "account_username"
}Read a specific account from a specific attribute. This will return a 401 status error if the user is not authenticated or does not have permission to view this attribute (sensitive).
HTTP method: GET
Endpoint: /pyacct/2/account/attribute/{key}/{value}
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Input data: null
Output data:
{
"id": -1,
"username": "account_username"
}Reads a specific attribute from a specific account by ID. This will return a 401 status error if the user is not authenticated or does not have permission to view this attribute (sensitive). This will return a 403 status error if the attribute specified is not unique. This will return a 404 status error if no such user exists.
HTTP method: GET
Endpoint path: /pyacct/2/account/{account_id}/attribute/{attribute}
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Input data: null
Output data:
{
"key" : "some_key",
"value" : "some_value"
}Given a session token, this endpoint allows for an account to update their username. This will not changed the account's ID or password, nor will it cause any valid tokens to expire. Like with login, this will return a 400 error status if the username is already taken, and should return a 200 status otherwise.
HTTP method: PUT
Endpoint path: /pyacct/2/account/username
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Input data:
{
"username": "new_account_username"
}Output data: null
Given a session token, this endpoint allows for an account to update their password. This will not changed the account's ID or username, nor will it cause any valid tokens to expire. Like with login, this will return a 400 error status if the passwords do not match, and should return a 200 status otherwise.
HTTP method: PUT
Endpoint path: /pyacct/2/account/password
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Input data:
{
"password": "new_account_password",
"password_confirmation": "new_account_password"
}Output data: null
Update one's own attribute. This can only be used to update someone's own attributes, and this should be validated by the UI.
HTTP method: PUT
Endpoint path: /pyacct/2/account/attribute
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Input data:
{
"key" : "some_key",
"value" : "some_value"
}Output data: null
Given a session token, this endpoint deletes the account tied to the token, as well as its username, password, and registered sessions.
HTTP method: DELETE
Endpoint path: /pyacct/2/account/
Content type: application/json
Authorization: Pass the access_token returned from the Create Session endpoint as the header token:
-H 'token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'Input data: null
Output data: null