-
Notifications
You must be signed in to change notification settings - Fork 10
API V1 Documentation
TransAM uses the JSend Specification for for all API JSON responses.
examples
{
"status" : "success",
"data" : {
"post" : { "id" : 1, "title" : "A blog post", "body" : "Some useful content" }
}
}
{
"status" : "fail",
"data" : { "title" : "A title is required" }
}
<base_url>/api/v1/<object>/<method>
In all requests, a X-User-Email and X-User-Token must be passed along with the request as a header.
Example:
--header "X-User-Email: [email protected]" --header "X-User-Token: vEUuxxx5zH9Z1wgZQ7PU"
If these headers are not provided, then request would be rejected.
Sign in an existing user, receiving auth token in response. After 4 failed attempts, account will be locked for 5 minutes.
POST api/v1/sign_in
Request must contain following parameters:
- email str [REQUIRED]
- password str [REQUIRED]
Example:
{
"email": "[email protected]",
"password": "testpw"
}
If successful, will return a success message and a session hash with authentication token. For example:
{
"status": "success",
"data": {
"message": "User Signed In Successfully",
"session": {
"name": "test user",
"email": "[email protected]",
"authentication_token": "_RGWWTV8YipKp15jmUwU",
"failed_attempts": 0
}
}
}
Sign out a user, reseting user auth token.
DELETE api/v1/sign_out
Request must include X-User-Email and X-User-Token headers to identify user. No request body is needed.
If successful, will return a success message. For example:
{
"status": "success",
"data": {
"message": "User [email protected] successfully signed out."
}
}
Retrieve user profile information
GET api/v1/users/profile
Request must contain following parameters:
- email str [REQUIRED]
Example:
{
"email": "[email protected]"
}
If successful, will return a user data hash. For example:
{
"status": "success",
"data": {
"user": {
"id": 1,
"name": "test user",
"email": "[email protected]",
"organization": {
"id": 1,
"name": "Test Organization",
"short_name": "TO"
}
}
}
}
List users for a specific organization
GET api/v1/users
Request must contain following parameters:
- organization_id number [REQUIRED]
Example:
{
"organization_id": 1
}
If successful, will return an organization data hash and list of user data. For example:
{
"status": "success",
"data": {
"organization": {
"id": 1,
"name": "Test Organization",
"short_name": "TO"
},
"users": [
{
"id": 1,
"name": "Test User",
"email": "[email protected]"
}
]
}
}
Retrieve organization basic information
GET api/v1/organizations/{id}
Request must contain following parameters in URL:
- id number [REQUIRED]
If successful, will return an organization data hash. For example:
{
"status": "success",
"data": {
"organization": {
"id": 1,
"name": "Test Organization",
"short_name": "TO"
}
}
}
Retrieve asset basic information
GET api/v1/assets/{object_key}
Request must contain following parameters in URL:
- object_key string [REQUIRED]
If successful, will return an asset data hash. For example:
{
"status": "success",
"data": {
"asset": {
"object_key": "A37I2NLMBFLG",
"asset_tag": "TEST_ASSET_TAG",
"organization_id": 1,
"transam_assetible_type": "Test Type",
"asset_subtype": "Test Asset Subtype",
"description": "This is a test asset",
"in_service_date": "11/23/2018"
}
}
}
Return basic info for a list of paginated assets
GET api/v1/assets
Request contains following parameters:
- page number [OPTIONAL]
- page_size number [OPTIONAL]
If successful, will return asset data array. For example:
{
"status": "success",
"data": {
"assets": [{
"object_key": "A37I2NLMBFLG",
"asset_tag": "TEST_ASSET_TAG",
"organization_id": 1,
"transam_assetible_type": "Test Type",
"asset_subtype_id": "1"
}]
}
}
Pagination information are embedded in the Link Header of the response, for example:
Link: <http://localhost:3000/assets?page=1>; rel="first",
<http://localhost:3000/assets?page=173>; rel="last",
<http://localhost:3000/assets?page=6>; rel="next",
<http://localhost:3000/assets?page=4>; rel="prev"
Total: 4321
Per-Page: 10
List documents
GET api/v1/{documentable_type}/{documentable_id}/documents
e.g., api/v1/assets/A3CFFNMLECIAd/documents
Request must contain following parameters in URL:
- documentable_type string [REQUIRED]
- documentable_id string [REQUIRED]
If successful, will return document array. For example:
{
"status": "success",
"data": {
"documents": [
{
"object_key": "A3CN063DDED2",
"description": "test document 1"
"url": "http://sample.com/test_doc_1.pdf"
},
{
"object_key": "A4CN0D3DDEF2",
"description": "test document 2"
"url": "http://sample.com/test_doc_2.pdf"
}
]
}
}
Upload one document
POST api/v1/{documentable_type}/{documentable_id}/documents
e.g., api/v1/assets/A3CFFNMLECIAd/documents
Request must contain following parameters in URL:
- documentable_type string [REQUIRED]
- documentable_id string [REQUIRED]
Then, contain following parameters in POST Body:
- document file [REQUIRED]
- description string [OPTIONAL]
If successful, will return uploaded document data. For example:
{
"status": "success",
"data": {
"document": {
"object_key": "A3CN063DDED2",
"description": "test document 1"
"url": "http://sample.com/test_doc_1.pdf"
}
}
}
Update one document
PATCH/PUT api/v1/{documentable_type}/{documentable_id}/documents/{id}
e.g., api/v1/assets/A3CFFNMLECIAd/documents/A3CN063DDED2
Request must contain following parameters in URL:
- documentable_type string [REQUIRED]
- documentable_id string [REQUIRED]
- id _string [required]
If successful, will return updated document data. For example:
{
"status": "success",
"data": {
"document": {
"object_key": "A3CN063DDED2",
"description": "updated test document 1"
"url": "http://sample.com/test_doc_1.pdf"
}
}
}
Delete one document
DELETE api/v1/{documentable_type}/{documentable_id}/documents/{id}
e.g., api/v1/assets/A3CFFNMLECIAd/documents/A3CN063DDED2
Request must contain following parameters in URL:
- documentable_type string [REQUIRED]
- documentable_id string [REQUIRED]
- id _string [required]
If successful, will return empty data hash. For example:
{
"status": "success",
"data": {}
}