Elentra API
  • Introduction
  • Developers
    • Getting Started
    • Quickstart Guide
      • Set up Repositories
      • Validate the setup
      • Exploring the API
      • Creating a new Module
      • Setup Routing
      • Introduction to Postman
      • Create a Controller
      • Using Eloquent Models
      • Input Validation
      • API Resource Authorization
  • Elentra API Standards
    • HTTP Methods & Status Codes
    • Routing & Parameters
      • Example Routing Patterns with HTTP Method
        • /courses/{course}/contacts
        • /courses/{course}/contacts?type={contact_type}
        • /courses/{course}/contacts/{contact}
        • /courses/{course}/syllabus
      • Common Mistakes
        • [GET] /admissions/file-review/file/rubric-score/{cycle_id}/{pool_id}/{subpool_id}
        • [DELETE] /notices/1,2,3
        • [GET] /cbe/curriculum/framework/{framework_id}/hierarchy-by-depth
        • [GET] /admissions/file-review/file/rubric-score/delete/{id}
        • [GET] /portfolio/entries/{entry_id}/get-file
        • [POST] /cbe/curriculum/updateframework
  • Automated Testing
    • Getting Started
      • Setting up a testing environment
      • Running Automated Tests
    • Seed Data
      • Folder Structure
      • Creating Seed Data
    • Functional Tests
      • Creating a Functional Test File
      • Testing HTTP Verbs
        • Creating an HTTP Test
        • GET Requests
        • POST / PUT / DELETE Requests
        • GraphQL Requests
      • Asserting API Response
      • Annotations
    • Code Style Linting
Powered by GitBook
On this page
  • Response Codes
  • This section contains the API standards and guidelines when implementing a GET route
  • This section contains the API standards and guidelines when implementing a POST route
  • This section contains the API standards and guidelines when implementing a PUT route
  • This section contains the API standards and guidelines when implementing a PATCH route
  • This section contains the API standards and guidelines when implementing a DELETE route
  1. Elentra API Standards

HTTP Methods & Status Codes

PreviousAPI Resource AuthorizationNextRouting & Parameters

Last updated 2 years ago

Response Codes

This section will describe the circumstances when you would return each possible HTTP status code that our endpoints typically respond with.

The examples below only briefly specify which types of URI paths and parameters are required to generate the responses described here.

Please see the sections for specific details on the structure of URI paths and query parameters.

This section contains the API standards and guidelines when implementing a GET route

GET /api/v2

The available response codes for a GET are listed below the header "Responses" Expand the response code to see the guidelines and standards.

Query Parameters

Name
Type
Description

*

String

Query parameters

Headers

Name
Type
Description

Authorization*

String

Bearer token

The request was successful.

The status code 204 No Content does not apply to GET requests. If required, then consider using the HEAD or OPTIONS verbs instead.

When request validation fails, 400 Bad Request status code is returned to the client.

Requirements

The response messaging should be clear and concise.

Scenario

400 may be returned if the query parameters of a GET request is invalid or missing.

This status code is returned to the client when the user is unauthenticated or the token has expired.

This status code is returned to the client when the user does not have permission to access the requested resource according to their ACL Role / Group.

No data should be returned if the user does not have permission.

This response code should be returned when the requested resource is not found.

Requirements

1. An empty collection should not return a 404 but a 200.

2. Any invalid URI with a non-existing resource identified in the URI will return a 404.

3. If a resource doesn't exist but is associated with the requested resource that does exist, then we should not send 404 as a response. For example, a course has been deleted, but the framework still exists.

4. If an internal dependency related to the resource being requested cannot be resolved, respond with 500.

Scenarios

1. The path contains a resource that doesn't exist i.e. /framework/1/tags where Framework 1 doesn't exist.

2. The endpoint needs to fetch data to retrieve the requested resource /courses/1/frameworks/1. If course 1 does not exist, we should return 404 since the course is in the path.

The client's request was valid, but the application had an issue. The user has no control over resolving the error.

Requirements

1. Error message should contain:

• Context of the issue

2. Error message should not contain:

• Leaked Data

• Stack Trace

• Responding with an SQL query that failed

3. Don't use 500 as a catch-all exception for other types of errors:

• Utilize 404 for not found resources

• Or other applicable 4xx response codes for client errors

4. When responding with 500, the error should be considered a bug. Therefore, it should be investigated and resolved so the client does not experience this again.

5. If an internal dependency related to the resource has not been found for the retrieval of any resource in the URI, we should respond with 500 instead.

Logging

Log detailed information on the server to allow technical personnel to debug and determine the cause of the error.

Scenario

When saving an entity that has a relationship that cannot be resolved, respond with 500.

This section contains the API standards and guidelines when implementing a POST route

POST /api/v2

The available response codes for a POST are listed below the header "Responses" Expand the response code to see the guidelines and standards.

Headers

Name
Type
Description

Authorization*

String

Bearer token

Request Body

Name
Type
Description

*

String

Request parameters

{...}

String

JSON request body

The request was successful.

The resource was created successfully.

This is the most common status code for POST. The body of the response should contain the newly created object.

Best practice

Set the location header to the URI of the new resource.

The 202 Accepted status code means that we will process the request in a:

• Queue

• Cron job

• Schedule

Suggestion

The response body may be empty with the relevant information set in the headers.

When responding with 204, the body must be empty.

Best practice

Set the location header to the URI of the new resource.

When request validation fails, 400 Bad Request status code is returned to the client. Requirements

The response messaging should be clear and concise.

Scenario

400 may return if the JSON, form submission data, query parameters, or file upload, is invalid or missing in the request body. Query parameters are uncommon for POST requests.

The 404 Not Found response code should be returned when the requested resource is not found.

Requirements

1. Posting to a non-existing collection should return a 404

2. Any invalid URI with a non-existing resource identified by the URI will return a 404

3. If an internal dependency related to the resource being requested cannot be resolved, respond with 500.

Scenarios

1. POST /courses/1/frameworks

If course 1 does not exist then return 404 should be returned to the client because the URI has a hierarchical dependency on the course.

2. POST /courses/1/frameworks/1

Return 404 due to it being a non-existent POST URI. This should be put instead of POST.

3. POST /courses/1/frameworks/add

POST to the framework collection directly.

Requirement:

Use HTTP Verbs with RESTful resource paths.

Avoid using verbs in the URI.

This status code is returned to the client when the user does not have permission to access the requested resource according to their ACL Role / Group.

No data should be returned if the user does not have permission.

The 409 Conflict status code is returned when there is a conflict while saving a resource, which might prevent the application from processing the request.

Scenarios:

1. A user already exists with the same email address or number.

2. When a unique property is being saved, and the new value is a duplicate of the existing value.

3. Anything that will violate data integrity e.g. a foreign key violation.

4. A violation of the state of dependent relationships to the object being saved.

5. Uploading a file older than the existing one.

The client's request was valid, but the application had an issue. The user has no control over resolving the error.

Requirements

1. Error message should contain:

• Context of the issue

2. Error message should not contain:

• Leaked Data

• Stack Trace

• Responding with an SQL query that failed

3. Don't use 500 as a catch-all exception for other types of errors:

• Utilize 404 for not found resources

• Or other applicable 4xx response codes for client errors

4. When responding with 500, the error should be considered a bug. Therefore, it should be investigated and resolved so the client does not experience this again.

5. If an internal dependency related to the resource being requested cannot be resolved, respond with 500.

Logging

Log detailed information on the server to allow technical personnel to debug and determine the cause of the error.

This status code is returned to the client when the user is unauthenticated or the token has expired.

This section contains the API standards and guidelines when implementing a PUT route

PUT /api/v2

The available response codes for a PUT are listed below the header "Responses" Expand the response code to see the guidelines and standards.

Headers

Name
Type
Description

Authorization*

String

Bearer token

Request Body

Name
Type
Description

*

String

Request parameters

{...}

String

JSON request body

The request was successful.

The resource was created successfully.

This is a less common status code for PUT. The body of the response should contain the newly created object.

Suggestion

A common practice is to set the location header to the URI of the newly created resource.

The 202 Accepted status code means that we will process the request in a:

• Queue

• Cron job

• Schedule

The response body should be empty.

Relevant information should be set in the headers.

Suggestion

The response body may be empty with the relevant information set in the headers.

When responding with 204, the body must be empty.

Suggestion

Set the location header to the newly created resource's URI.

When request validation fails, 400 Bad Request status code is returned to the client. Requirements

The response messaging should be clear and concise.

Scenario

400 may return if the JSON, form submission data, query parameters, or file upload, is invalid or missing in the request body. Query parameters are uncommon for PUT requests.

This status code is returned to the client when the user is unauthenticated or the token has expired.

This status code is returned to the client when the user does not have permission to access the requested resource according to their ACL Role / Group.

No data should be returned if the user does not have permission.

The 404 Not Found response code should be returned when the requested resource was not found.

Requirements

1. Any invalid URI with a non-existing resource identified by the URI will return a 404, unless the implementation allows creating an object using PUT.

2. If an internal dependency related to the resource being requested cannot be resolved, respond with 500.

Scenarios

1. PUT /courses/1/frameworks

If course 1 doesn't exist we should return 404 since the course is the path. This is a hierarchical dependency in the URI.

2. PUT /courses/1/frameworks/update

PUT to the framework collection directly.

Requirement:

Use HTTP Verbs with RESTful resource paths.

Avoid using verbs in the URI.

The 409 Conflict status code is returned when there is a conflict while saving an object, which might prevent the application from processing the request.

Scenarios:

1. A user already exists with the same email address or number.

2. When a unique property is being saved, and the new value is a duplicate of the existing value

3. Anything that will violate data integrity e.g. a foreign key violation

4. A violation of the state of dependent relationships to the object being saved.

5. Uploading a file older than the existing one.

The client's request was valid, but the application had an issue. The user has no control over resolving the error.

Requirements:

1. Error message should contain:

• Context of the issue

2. Error message should not contain:

• Leaked Data

• Stack Trace

• Responding with an SQL query that failed

3. Don't use 500 as a catch-all exception for other types of errors:

• Utilize 404 for not found resources

• Or other applicable 4xx response codes for client errors

4. When responding with 500, the error should be considered a bug. Therefore, it should be investigated and resolved so the client does not experience this again.

5. If an internal dependency related to the resource being requested cannot be resolved, respond with 500.

Logging

Log detailed information on the server to allow technical personnel to debug and determine the cause of the error.

This section contains the API standards and guidelines when implementing a PATCH route

PATCH /api/v2

The available response codes for a PATCH are listed below the header "Responses" Expand the response code to see the guidelines and standards.

Headers

Name
Type
Description

Authorization*

String

Bearer token

Request Body

Name
Type
Description

*

String

Request parameters

{...}

String

JSON request body

The request was successful.

The 202 Accepted status code means that we will process the request in a:

• Queue

• Cron job

• Schedule

The response body should be empty.

Relevant information should be set in the headers.

Suggestion

The response body may be empty with the relevant information set in the headers.

When responding with 204, the body must be empty.

The Patch request conducted multiple requests that required multiple response codes, like a batch job.

Example

PATCH /frameworks?query=123 could update any frameworks matching the query, and each update may have a different status code (200, 404, 400, etc.)

When request validation fails, 400 Bad Request status code is returned to the client. Requirements

The response messaging should be clear and concise.

Scenario

400 may return if the JSON, form submission data, query parameters, or file upload, is invalid or missing in the request body. Query parameters are uncommon for PATCH requests.

This status code is returned to the client when the user is unauthenticated or the token has expired.

This status code is returned to the client when the user does not have permission to access the requested resource according to their ACL Role / Group.

No data should be returned if the user does not have permission.

The 404 Not Found response code should be returned when the requested resource is not found.

Requirements

1. Any invalid URI with a non-existing resource identified by the URI will return a 404, unless the implementation allows creating an object using PATCH.

2. If an internal dependency related to the resource has not been found for the retrieval of any resource in the URI, we should return 500 instead.

Scenarios

1. PATCH /courses/1/frameworks

If course 1 doesn't exist we should return 404 since the course is the path. This is a hierarchical dependency in the URI.

2. PATCH /courses/1/frameworks/update

PATCH to the framework collection directly.

Requirement:

Use HTTP Verbs with RESTful resource paths.

Avoid using verbs in the URI.

The 409 Conflict status code is returned when there is a conflict while saving an object, which might prevent the application from processing the request.

Scenarios

1. Anything that will violate data integrity e.g. a foreign key violation.

2. Deleting the object violates a business relationship. This does not have to be a foreign key violation in the database. Soft deletes will not trigger a foreign key violation but they might cause a business relationship violation.

3. Deleting a lottery with stages still active.

4. Framework deleted when already associated with a tree.

Use graphQL for complicated batch jobs or complex queries.

The client's request was valid, but the application had an issue. The user has no control over resolving the error.

Requirements

1. Error message should contain:

• Context of the issue

2. Error message should not contain:

• Leaked Data

• Stack Trace

• Responding with an SQL query that failed

3. Don't use 500 as a catch-all exception for other types of errors:

• Utilize 404 for not found resources

• Or other applicable 4xx response codes for client errors

4. When responding with 500, the error should be considered a bug. Therefore, it should be investigated and resolved so the client does not experience this again.

5. If an internal dependency related to the resource being requested cannot be resolved, respond with 500.

Logging

Log detailed information on the server to allow technical personnel to debug and determine the cause of the error.

This section contains the API standards and guidelines when implementing a DELETE route

DELETE /api/v2

The available response codes for a DELETE are listed below the header "Responses" Expand the response code to see the guidelines and standards.

Query Parameters

Name
Type
Description

*

String

Query parameters

Headers

Name
Type
Description

Authorization*

String

Bearer token

The request was successful.

The 202 Accepted status code means that we will process the request in a:

• Queue

• Cron job

• Schedule

The response body should be empty.

Relevant information should be set in the headers.

Suggestion

The response body may be empty with the relevant information set in the headers.

When responding with 204, the body must be empty.

This status code is returned to the client when the user is unauthenticated or the token has expired.

This status code is returned to the client when the user does not have permission to access the requested resource according to their ACL Role / Group.

No data should be returned if the user does not have permission.

The 404 Not Found response code should be returned when the requested resource is not found.

Requirements

1. Any invalid URI with a non-existing resource identified by the URI will return a 404.

2. If an internal dependency related to the resource has not been found for the retrieval of any resource in the URI, we should return 500 instead.

Scenarios

1. DELETE /courses/1/frameworks

If course 1 doesn't exist we should return 404 since the course is the path. This is a hierarchical dependency in the URI.

2. DELETE /courses/1/frameworks/delete

DELETE to the framework collection directly.

Requirement

Use HTTP Verbs with RESTful resource paths.

Avoid using verbs in the URI.

The 409 Conflict status code is returned when there is a conflict while saving an object, which might prevent the application from processing the request.

Scenarios:

1. Anything that will violate data integrity e.g. a foreign key violation.

2. Deleting the object violates a business relationship. This does not have to be a foreign key violation in the database. Soft deletes will not trigger a foreign key violation but they might cause a business relationship violation.

3. Deleting a lottery with stages still active.

4. If an exam is active when deleting a question.

5. Framework deleted when already associated with a tree.

The client's request was valid, but the application had an issue. The user has no control over resolving the error.

Requirements

1. Error message should contain:

• Context of the issue

2. Error message should not contain:

• Leaked Data

• Stack Trace

• Responding with an SQL query that failed

3. Don't use 500 as a catch-all exception for other types of errors:

• Utilize 404 for not found resources

• Or other applicable 4xx response codes for client errors

4. When responding with 500, the error should be considered a bug. Therefore, it should be investigated and resolved so the client does not experience this again.

5. If an internal dependency related to the resource being requested cannot be resolved, respond with 500.

Logging

Log detailed information on the server to allow technical personnel to debug and determine the cause of the error.

When request validation fails, 400 Bad Request status code is returned to the client.

Requirements

The response messaging should be clear and concise.

Scenario

400 may return if the JSON, form submission data, query parameters, or file upload, is invalid or missing in the request body. Query parameters are uncommon for Delete requests.

Routing and Parameters