REST API Requirements

Learn about the requirements for a REST API to be compatible with Connectors

Connectors make it easy to build a GraphQL API using your existing HTTP/JSON APIs. They're flexible and work with most APIs, especially if they conform to the following guidelines.

Content Type

Connectors expect a JSON response body. If your API endpoint doesn't default to a JSON content type, you may need to specify an Accept: application/json header. See the requests guide to learn how to set headers.

Some APIs may have a different mechanism for specifying the response content type, such as a query parameter or file extension. Ensure your Connector is configured appropriately to request a JSON response.

note
Connectors don't require a Content-Type response header. By default, they interpret any response body as JSON.

Core JSON-over-HTTP requirements

Connectors work with APIs that follow these JSON-over-HTTP principles:

  • Your endpoints accept requests using these HTTP verbs: GET, POST, PUT, PATCH, DELETE.

  • Your endpoints use path segments and query string parameters for inputs, such as /users/123 or /users?limit=10.

  • For POST, PUT, and PATCH requests with request bodies, your endpoints accept JSON or form URL encoded strings.

  • Your endpoints respond with JSON values—typically objects, but any JSON value is allowed.

  • Your endpoints always return a status code between 200 and 299 for successful requests.

  • Your endpoints provide a known set of properties. GraphQL doesn't have a Map type, so you must define the mapping between JSON properties and GraphQL fields in advance. (You can map an arbitrary map to a scalar field using a custom scalar type.)

Entity representation and relationships

Connectors work best with APIs that follow these conventions for representing and retrieving entities:

  • You represent your entities across various endpoints using the same identifiers. For example, a User is consistently identified by 123 across all endpoints.

  • You provide endpoints to fetch an entity by its primary key. For example, /users/123 returns the user with ID 123.

  • Your endpoints use simple values for foreign keys. For example, a User object has a companyId field containing the ID of the company it belongs to. (Using a full URL such as {"company": "http://myapi.com/company/234"} is difficult to work with).

  • When appropriate, your endpoints embed related entities in the response. For example, a User object might include a company field that contains a Company object.

Security conventions

To ensure secure interactions, your API should follow these security best practices.

  • Your endpoints perform their own authentication and authorization checks as necessary. You can add layers of additional security using GraphOS Router's security features.

  • Your endpoints accept authentication information in request headers. The headers can come directly from the client or be injected by the router.

  • Your endpoints don't use query parameters for sensitive information. The router emits full URLs in logs and traces.
Feedback

Ask Community