RESTful Concepts

RESTful Concepts

JSON

JSON (JavaScript Object Notation) is a lightweight data interchange format that’s easy for humans to read and write. The Revelation helpdesk API fully supports JSON formatted data and is the primary format for sending and retrieving data.

HTTP Verbs

HTTP verbs help define the actions that can be performed on the resources in the Revelation helpdesk API, making the API more intuitive and easier to use.

  1. GET: Retrieves data from the server. It’s used to fetch a resource or a collection of resources. GET requests do not modify any data.
  2. POST: Sends data to the server to create a new resource. Can also be used to update an existing resource if the ID is specified.
  3. PUT: Updates an existing resource using its ID.
  4. DELETE: Removes a resource from the server.
  5. PATCH: Partially updates an existing resource. Unlike PUT, which replaces the entire resource, PATCH applies partial modifications.

HTTP Response Codes

Each request to the Revelation helpdesk API endpoints will generate an HTTP response code.  Common response codes fall into three possible categories, any in the 2xx range indicates success, any in the 4xx range indicates a problem with the request and 5xx range indicates an error on the server side.

Some common response codes you will encounter when calling the Revelation helpdesk API endpoints are:

  • HTTP 200 – OK: Indicates that the operation was successful.
  • HTTP 201 – Created: This response indicates that a new resource was created. This is usually returned when performing a POST request to create a new item.
  • HTTP 204 – No Content: The request was successful, but no data was retrieved.
  • HTTP 400 – Bad Request: This indicates that a bad parameter value was supplied such as a missing value, value out of range, incorrect ID, or the endpoint format is incorrect. The response body will have more details regarding the incorrect format and which values in the request are invalid.
  • HTTP 401 – Unauthorized: The request was rejected because the authentication token is either invalid or expired. The response body will have more details regarding the problem.
  • HTTP 403 – Forbidden: The user performing the request has insufficient permissions to perform this request on the current endpoint. This can also indicate that the scope in the access token does not have sufficient permissions to call this endpoint.
  • HTTP 404 – Not Found: The resource you are looking for could not be found. This includes calling an endpoint that does not exist or trying a GET request using a resource ID parameter that does not exist. The response body will have more details regarding the problem.
  • HTTP 500 – Internal server error: A code exception was thrown on the web server. To investigate further, review the errors in the Application Windows Event Log. For security reasons, detailed error messages are not returned by the API.
  • HTTP 503 – Service Unavailable: This indicates that there is a problem with the IIS web server that hosts the API.