REST API Conventions

All Ed-Fi API specifications are based on the Hypertext Transfer Protocol and follow the semantics described for that protocol. Furthermore, these API specifications follow the REST (REpresentational State Transfer) architectural style. These API Design Guidelines highlight particular aspects of these protocols as they apply to an Ed-Fi API.

Verbs

HTTP verbs communicate actions that can be taken against a resource. An Ed-Fi API can support only the GET verb, when providing a read-only interface. Otherwise, an Ed-Fi API must support the following HTTP verbs: POST, GET, PUT, and DELETE. Each verb has specific usage patterns with respect to URL construction, HTTP headers, request bodies, response bodies, and status codes. These are described in separate pages for each.

POST Requests for creating items
GET Requests for retrieving items
PUT Requests for updating items
DELETE Requests for deleting items

An HTTP PATCH performs a partial update on an existing individual resource. For a partial update, only the properties that are submitted will be updated on the target resource. The entire patch will be applied, or none of it will. The new representation of the entire resource is returned in the response body. Due to a lack of industry standard practice in the use of PATCH for REST APIs, it is not recommended that implementations support PATCH in Ed-Fi API applications.

Content Type

For all Ed-Fi API transactional requests and responses, JSON must be the default format. If a media-type header is not provided, "application/json" is presumed. Alternate packet formats may also be supported.

Authentication

To safeguard student data, an Ed-Fi API must require authentication and implement one or more authorization schemes. Exception: the Discovery API does not provide access to student data and must be accessible to anonymous clients. The API application must support the Authorization header and should support OAuth 2.0 style authentication using the client credentials grant.

For more detail on authentication and authorization, see the Handling Authentication and Authorization.

Status Codes

The list below contains the HTTP status codes most likely to be used in an Ed-Fi API; other canonical status codes may be used in appropriate circumstances.

Code	Meaning	When to Use

Code	Meaning	When to Use
200	OK	The requested resource was successfully retrieved.
201	Created	The item was created.
204	No Content	The resource was successfully updated or deleted.
304	Not Modified	The item's ETag value matched the `If-None-Match` header value; the resource has not been modified.
400	Bad Request	The request was invalid and cannot be completed. See the response body for specific validation errors.
401	Unauthorized	The request requires authentication. The OAuth bearer token was either not provided or is invalid.
403	Forbidden	The request cannot be completed in the current authorization context.
404	NotFound	The resource could not be found.
405	Not Allowed	Special cases where a verb is not allowed, for example in a read-only API.
409	Conflict	The request cannot be completed because it would result in an invalid state.
412	Precondition Failed	The resource's current server-side ETag value does not match the supplied If-Match header value in the request.
429	Too Many Requests	Too many requests have been received from the client (rate limiting).
500	Server Error	An unhandled error occurred on the server.
502	Bad Gateway	A network resource is not available (e.g. web server misconfiguration; unreachable database).

Error Handling

Requests that result in an error must receive a standard HTTP status code in the response. The applicable status codes are listed in the sections for each verb. In situations where a response body is warranted, for providing detailed information on the error, the response should follow the Problem Details for HTTP APIs specification.

When reporting on error details, the API implementation must carefully consider the potential for leakage of Personally Identifiable Information (PII) or other sensitive information.

ETags

ETags (Entity Tags) are mechanisms used to support optimistic concurrency and efficient bandwidth handling. The use of ETags is recommended for Ed-Fi REST API implementations.

Also see Handling Optimistic Concurrency with ETags for further guidance on implementing ETags.