Skip to content

API documentation

Jump to bottom
mayuriardad edited this page Jul 3, 2020 · 54 revisions

API Error codes

  • 401: Invalid token (Unauthorised)
  • 403: Access error
  • 400: Validation error or URL is incorrect for APIs (POST, PUT)
  • 404: Incorrect URLs (id incorrect) for GET API
  • 422: Unprocessable entity
  • 500: Internal server error

API success codes

  • 201: Status created (POST Requests)
  • 200: Status ok

Error Response:

{
 error: {
   code: "invalid_data"
   message: "Please provide valid form data"

   fields: {
     "field_name": "Error message",
     "field_name": "Error message"
   }
 }
}

Note: fields section in error response will be present only when token is valid and there are form validation errors

Request Headers:

{
  "Content-Type": "application/json",
  "Accept": "application/vnd.peerly.v1",
  "Authorization": `Bearer ${apiToken}`
}

API Endpoints

1. Google login

POST /oauth/google

Payload:

access_token: "" (required)

Note: Validation must be present to check if signin email used for login belongs to valid organisation domain

Success Response:

Status code: 200 (ok)

{
  data: {
    token: <string>
  }
}

### Claims inside JWT token:

iss: "node.peerly.com"
sub: <user-id> or <uuid> to uniquely identify a user
aud: <base url of react ui> (for now it can be "peerly.com")
exp: epoch (seconds) - on or after which it will not be accepted
nbf: epoch (seconds) - token older than this time won't be accepted
iat: epoch (seconds) - time of issuing the token
"https://peerly.com": {
   "roleId": <role-id>,
   "orgId": <org-id>,
   "orgName": "<name of org>"
 }

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_organization"
    message: "unauthorized user"
  }
}

Status Code: 500 (InternalServerError)

{ 
  "error": {
     message: "internal server error"
  }
}

2. Logout

POST /logout

Success Response:

Status code: 200 (ok)

Error Response:

Status Code: 500 (InternalServerError)

{ 
  "error": {
     message: "internal server error"
  }
}

3. Core Values

POST /core_values

Payload:

"description": "" (required)
"text": "" (required)
"parent_core_value_id": null (optional)
"thumbnail_url" : <s3_bucket_url_after_image_upload>

Success Response:

Status code: 201 (created)

{
  data: {
    "id": <id>,
    "description": <description>,
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id> (default null)
    "org_id": <organisation_id>
  } 
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

Status Code: 400 (Invalid request)

{
 error: {
   code: "invalid_data"
   message: "Invalid core value data"

   fields: {
     "field_name": "Error message",
     "field_name": "Error message"
   }
 }
}

PUT /core_values/:id

Payload:

"description": "" (required)
"text": "" (required)
"thumbnail_url" : <s3_bucket_url_after_image_upload>

Success Response:

Status code: 200 (ok)

{
  data: {
    "id": <id>
    "description": <description>
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>
    "org_id": <organisation_id>
  }
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

Status Code: 400 (Invalid request)

{
 error: {
   code: "invalid_data"
   message: "Invalid core value data"

   fields: {
     "field_name": "Error message",
     "field_name": "Error message"
   }
 }
}

GET /core_values

Success Response:

Status code: 200 (ok)

{
  data: [{
    "id":<id>,
    "description": <description>,
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>,
    "org_id": <organisation_id>,
    "thumbnail_url": <thumbnail_url_string>
  }.
  {
    "id":<id>,
    "description": <description>,
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>,
    "org_id": <organisation_id>,
    "thumbnail_url": <thumbnail_url_string>
  }]
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

GET /core_values/:id

Success Response:

Status code: 200 (ok)

{
  data: {
    "id":<id>
    "description": <description>
    "text": <core_value_text>,
    "parent_core_value_id": <parent_id>
    "org_id": <organisation_id>
    "thumbnail": <thumbnail_url_string>
  }
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

4. Users

GET /users

Query Params

  • limit (optional)
  • offset (optional)
  • starts_with (optional) search by text
  • org_id (optional only for super admin access)

Success Response:

Status code: 200 (ok)

{
  data: [{
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
    "soft_delete_by": <user_id>
    "soft_delete_at": <timestamp>
  }.
  {
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
    "soft_delete_by": <user_id>
    "soft_delete_at": <timestamp>
  }]
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

GET /users/:id (For admin only)

Note: For fetching profile information of a logged in user API endpoint should be

GET /users/me

Success Response:

Status code: 200 (ok)

{
  data: {
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
    "hi5_count": <number>
  }
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

PUT /users/me

Payload

"first_name": <first_name> (required)
"last_name": <last_name> (required)
"display_name": <display_name> (required)
"profile_image_url": <profile_image_url> (optional)

Success Response:

Status code: 200 (ok)

{
  data: {
    "id":<id>
    "first_name": <first_name>
    "last_name": <last_name>
    "email": <email>,
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
    "role_id": <role_id>
    "hi5_quota_balance":<hi5_quota_balance>
    "org_id": <organisation_id>
  }
}

PUT /users/:id (for admin only)

Payload

"role_id": <role_id> (required)

Success Response:

Status code: 200 (ok)

DELETE /users/:id (for admin only) Soft deletes the user

Success Response:

Status code: 200 (ok)

Note: No POST API for users they will be created by login

5. Recognitions

GET /recognitions

Query params

  • top_hi5_recognitions (default 5)
  • from_date: (default null) format epoch
  • to_date: (default null) format epoch/ date obj UTC
  • given_to array_of[<user_id>]
  • given_by array_of[<user_id>]
  • core_value_ids array_of[<core_value_ids>]
  • limit (optional)
  • offset (optional)

Success Response:

Status code: 200 (ok)

{
  data: [{
    "id":<id>
    "text": <recognition_text>,
    "given_for_user": {
          id: <user_id>,
          first_name: <string>,
          last_name: <string>
          profile_image_url:<url_string>
     },
    "given_by_user" : {
          id: <user_id>,
          first_name: <string>,
          last_name: <string>
          profile_image_url:<url_string>
    },
    "given_at": <timestamp>,
    "coreValue":{
         "id": <core_value_id>,
         "text": <core_value_text>,
         "description": <desc>
         "thumbnail": <icon_img_url>
    },
    "hi5_count": <number>
  }.
  {
    "id":<id>,
    "text": <recognition_text>,
    "given_for_user": {
          id: <user_id>,
          first_name: <string>,
          last_name: <string>
          profile_image_url:<url_string>
     },
    "given_by_user" : {
          id: <user_id>,
          first_name: <string>,
          last_name: <string>
          profile_image_url:<url_string>
    },
    "given_at": <timestamp>,
    "coreValue":{
         "id": <core_value_id>,
         "text": <core_value_text>,
         "description": <desc>
         "thumbnail": <icon_img_url>
    },
    "hi5_count": <number>
 }]
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

POST /recognitions

Payload

  • given_for_user (required)
  • core_value_id (required)
  • text (required)

Success Response:

Status code: 201 (created)

{
  data: {
    "id":<id>
    "core_values_id": <core_value_id>
    "text": <recognition_text>,
    "given_for_user": <user_id>
    "given_by_user": <user_id>
    "given_at": <timestamp>
  } 
}

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

6. Recognition Hi5

POST /recognitions/:recognition_id/hi5

Payload

  • comment (optional)

Success Response:

Status code: 201 (created)

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

Status Code: 400

{ 
  "error": {
     code: "insufficient_hi5_balance"
     message: "Hi5 quota balance is insufficient for this action"
  }
}

GET /recognitions/:recognition_id/hi5

Query params

  • limit (optional)
  • offset (optional)

Success Response:

Status code: 201 (created)

{
  data: [{
    "user_id":<id>
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
  },{
    "user_id":<id>
    "display_name": <display_name>
    "profile_image_url": <profile_image_url>
  }]

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

7. Recognition reporting and moderation

POST recognitions/:recognition_id/report

Payload

mark_as: <string> (required) and one of ["fraud", "not_relevant", "incorrect"]
reason: <text> (required)

Success Response:

Status code: 201 (created)

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

POST recognitions/:recognition_id/review

Payload

is_inappropriate: <bool> (required)
comment: <text> (optional)

Success Response:

Status code: 201 (created)

Error Response:

Status Code: 401 (Unauthorized)

{ 
  "error": {
    code: "invalid_token"
    message: "unauthorized user"
  }
}

Status Code: 403 (forbidden)

{ 
  "error": {
     code: "access_denied"
     message: "Permission required"
  }
}

7. Image Upload

GET /s3_signed_url

Query params

  • type (required) (either profile or core_value)

Success Response:

Status code: 200 (ok)

{
  data: {
     s3_signed_url: <string>
  }
}

Copyright © Josh Software Pvt. Ltd.

Clone this wiki locally