Reference

Referential information on some of the API standards are available below.

Status Codes

The GraphQL API returns a standard HTTP status code in the Response header.

HTTP Status Code	Description
200 OK	The request was successfully completed.
202 Accepted	The request has been accepted for processing, but the processing has not been completed. The request may or may not eventually be acted upon, as it may be disallowed at the time processing takes place.
400 Bad Request	The request could not be processed because it contains missing or invalid information (such as, a validation error on an input field, a missing required value, and so on).
401 Unauthorized	The request is not authorized. The authentication credentials included with this request are missing or invalid.
403 Forbidden	The user cannot be authenticated. The user does not have authorization to perform this request.
404 Not Found	The request includes a resource URI that does not exist.
415 Not Acceptable	The client's ContentType header is not correct. For example, the client attempts to send the request in XML, but the resource can only accept JSON.
500 Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.
503 Service Unavailable	The server is unable to handle the request due to temporary overloading or maintenance of the server. The web application is not currently running.

All responses are in JSON, and follow the guidelines of well-formed JSON.

The Oracle Utilities GraphQL APIs use the standard connections pattern for pagination.

The following topics can assist users who are more familiar with REST APIs to be aware of how certain concepts and techniques work for GraphQL APIs:

Data Requests:
- REST API: The client makes a request to a specific endpoint and receives all the data associated with that endpoint
- GraphQL API: The client sends a query specifying the data required, and only that data is returned.
Response Format:
- REST API: The response format is fixed and determined by the server.
- GraphQL API: The client specifies the desired format of the response, allowing for more flexibility in the data returned.
Multiple Requests:
- REST API: It may be necessary to make multiple requests to different endpoints to get all the data needed.
- GraphQL API: All the data can be retrieved with a single request, making it more efficient for certain use cases.
Versioning:
- REST API: Different versions of the API are typically created to maintain backward compatibility.
- GraphQL API: New features can be added without affecting existing queries.
Caching: REST APIs are built to leverage the network-level caching built into the internet, but GraphQL requests cannot be cached by intermediate network infrastructure. Since our GraphQL APIs work with account-specific data that usually changes with each request and would not be shared by many web sessions, the lack of caching support is not a significant downside for our APIs.