...
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.
...
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 API Implementation Guidelines: 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 |
|---|---|---|
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 |
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.
...
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.