When issuing a request for a collection of records e.g. getAllOrgs() (with an endpoint of .../orgs) an HTTP 404 MUST NOT be returned. An HTTP Code 200 MUST be returned when records are returned and when there are no records to be returned. The most common scenario when there may be no records to be returned is when a filter query parameter is used e.g. filter on the status of the record.  Such a request would have the form:


In this case, if there are no Org records' with a 'status=tobedeleted' then a HTTP Code of 200 is returned with no content.

When issuing a request on a related collection of records e.g. getTeachersForSchool() then an HTTP Code of 404 MUST be returned if the related record cannot be found. Using the example of:


then an HTTP Code of 404 MUST be returned if the School record with a sourcedId of 'schoolSourcedID' cannot be found. In such a case an incorrect 'sourcedId' has been supplied and so the request is invalid. If the specified school can be located then an HTTP Code of 200 MUST be returned  irrespective if whether or not any Teacher records are returned. The same rule applies if the URL contains more than one identifier e.g. a request for the set of Enrollments for a Class in a School (this requires the provision of identifiers for both the Class and School).

When issuing a request for a specific record e.g. getOrg() (with an  endpoint of .../orgs/{orgSourcedId}) an HTTP 404 code MUST be returned when the specified record cannot be provided. The corresponding error status report MUST be returned.  This means that there are subtle differences in behaviour  when obtaining a single record.  Consider the two ways in which a single User record can be obtained:

[1]        .../users/{userSourcedId}                                               getUser()

[2]        .../users?filter=sourcedId='userSourcedId'                 getAllUsers() + filter Query Parameter

Assuming the requests are well formed. In method [1] a HTTP Code 200 will be returned when the record is supplied and a HTTP Code 404 when no record can be located. For method [2] only a HTTP Code 200 will be returned. The key point is that in method [1] an error has occurred because the expected record is absent.  In method [2]  the request is a query on a valid set of records and no records is still a successfully completed query.

Whenever an HTTP Code of 404 is returned, the accompanying error payload MUST be supplied.