C106p01eapimexternalstg.blob.core.windows.net

?DfE Attendance APILifecycle stageDevelopment1. OverviewThe Attendance API has been developed to provide the ability to submit attendance data of schools. It allows MIS software developers of schools to connect with the DfE Developer Hub and submit the summarised attendance data on the behalf of schools securely to a restricted endpoint.2. VersioningWhen an API changes, we will strive to make backwards compatible changes were possible. When this is not possible, we will provide a notice on ratedeprecated endpoints and make a new endpoint available.3. API browser and swagger fileFor more detailed information on each API action, you can:open the API browserlook at the API Swagger fileYou can also generate a client library from the Swagger file using the Swagger editor.This project uses the OpenAPI 3.0 specification so Swagger tools used need to support this specification4. AuthenticationTo be able to access the DfE Attendance API you need to be authenticated. If you don’t already have a developer hub account you will need to create one. Please refer to the ‘overview’ link within the top navigation of the developer hub for details on how to set up authentication for your organisation.5. Consent processAccess to the DfE Attendance API does not utilise a consent process. 6. HTTP status codesThe DfE Information API uses standard HTTP response code conventions:100 codes are informational200 codes indicate success300 codes indicate a redirection400 codes indicate a client-side error500 codes indicate a server-side errorCommon status codes are:HTTP Status codeMessageComments200OKThis status code indicates that the request has been processed successfully201CreatedCreated success status response code indicates that the request has succeeded and has led to the creation of a resource (used for post requests with no errors)202AcceptedAccepted response status code indicates that the request has been accepted for processing, but the processing has not been completed (used for post requests with some errors)400Bad RequestThis status code indicates that the incoming request body or parameters do not conform with the OpenAPI/Swagger document which describes the APIThis error code could also include specific message to indicate the problem in the requested payload (e.g. Unexpected URN).example: Invalid or Empty URN401UnauthorisedThis status code indicates authentication or authorisation error. This could be sent due to various reason such as missing JWT header, Invalid claims, Invalid subscription key etc. For security reasons, error responses for this status code will not include reason.403Service UnavailableThis status code indicates that the service is currently unavailable429Too Many RequestsThis status code indicates that the throttling limit of a client has be exceeded504Gateway TimeoutThis status code indicates that there is a network connection problem within the layers of the API fulfilment stack7. API error codesThere are no specific API error codes for the DfE Attendance API. We are using http status code to indicate a successful call to API or any failure. In case of validation failure or malformed payload HTTP error code 400 will be sent with reason of failure.Please see the POST /data/attendances for details of validation errors that may be returned on when a submission is made with a valid URN but with data element(s) that contain errors.8. Rate LimitingWe have introduced limits on API usage rates in terms of requests per minute.If you exceed this limit, you will receive a 429 Too Many Requests HTTP status code for each request made within the remainder of the time.For example, per minute, you can make:Up to 1000 requests per endpoint for the same API client/IP address.Rate limiting threshold is subject to change based on the further engagement with API client developer.9. EndpointsSubmit all the available attendance codes of the NC Year Group aggregated values for a specified urn2540421005"SubmissionRequest" : {"urn" : "integer""submissionData" : [{"ncYearGroup" : "string""date" : "string""schoolSession" : "string""pupilsOnRoll" : "integer""attendances" :[{"attendanceCode" : "string""value" : "integer"}]}]}020000"SubmissionRequest" : {"urn" : "integer""submissionData" : [{"ncYearGroup" : "string""date" : "string""schoolSession" : "string""pupilsOnRoll" : "integer""attendances" :[{"attendanceCode" : "string""value" : "integer"}]}]}POST RepresentationParameter NameTypeDescriptionSubmissionRequestobjectThe submission requesturnintegerThe provider URNSee GET /provider/{urn}submissionData[]listList of data submissionssubmissionData[].ncYearGroupThe NC Year GroupSee GET /codes/ncyeargroupsubmissionData[].datestringDate in ISO8601:2004 format e.g. 2020-10-13submissionData[].schoolSessionstringLimited toAMPMsubmissionData[].pupilsOnRollintegerAn unsigned integer The Number of pupils on Roll in a YearGroup for the contained SubmissionData.This is used check completeness of attendances recording and percentage attendances for a year groupsubmissionData[].attendances[]listList of attendancessubmissionData[].attendances[].attendanceCodestringThe attendance CodeSee GET /codes/attendancesubmissionData[].attendances[].valueintAn unsigned integer 2540421005"SubmissionResponse" : {"submissionRef" : "string""errors" : [{"id" : "string""code" : "string""status" : "string""title" : "string""detail" : "string""path" : "string"}]}020000"SubmissionResponse" : {"submissionRef" : "string""errors" : [{"id" : "string""code" : "string""status" : "string""title" : "string""detail" : "string""path" : "string"}]}Response RepresentationParameter NameTypeDescriptionSubmissionResponseobjectThe submission responsesubmissionRefstringThe unique submission responseerrors[]listList of errorserrors[].idstringError String errors[].codestringError Code Shorterrors[].statusstringError Statuserrors[].titlestringError Title in human readable formerrors[].detailstringError Detail for fatal errors this is an extended error messageFor non-fatal errors this is the value that caused the errorerrors[].pathstringFor non-fatal errors a json path to the element that caused the error, this is designed to aid in error identification and resolutionData Validation ErrorsAny data that has a valid schema and urn will be accepted and a submission reference will be returned along with any data validation errorsIDCodeStatusTitleDetailFAILURE_INVALID_NCYEARGROUP_CODEVAL103Invalid NC Year Group CodeFAILURE_INVALID_ATTENDANCE_CODEVAL104Invalid Attendance CodeFAILURE_INVALID_ATTENDANCE_VALUEVAL105Invalid Attendance ValueFAILURE_INVALID_PUPILSONROLL_VALUEVAL106Invalid PupilsOnRole ValueData UpdatessubmissionData is considered atomic for any valid combination of urn ncYearGroup date and schoolSessionThis means that any change of attendance records in a particular year group on a particular day and session must be represented by an update of all attendances for that year group day and sessionGET /provider/{urn}Get details of the specified provider this will only provide details of providers who can submit data using this API so can be used to verify that the urn provided corresponds to the expected school and that data would be accepted if provided.URN is the School Unique Reference Number.All data provided by this API endpoint is from NameTypeDescriptionurnintegerThe provider URNIf successful, this returns a Provider Object2540425450Provider{"urn" : "integer""name" : "string""address" : "string""phaseOfEducation" : "string""schoolType" : "string"}020000Provider{"urn" : "integer""name" : "string""address" : "string""phaseOfEducation" : "string""schoolType" : "string"}Resource RepresentationParameter NameTypeDescriptionurnintegerThe provider URNnamestringThe Establishment NameaddressstringThe Establishment AddressphaseOfEducationstringThe Phase of educationInitial possible values are16 plusAll-throughMiddle deemed primaryMiddle deemed secondaryNot applicableNurseryPrimarySecondaryschoolTypestringThe School Type Initial possible values areAcademy 16 to 19 sponsor ledAcademy 16-19 converterAcademy alternative provision converterAcademy alternative provision sponsor ledAcademy converterAcademy special converterAcademy special sponsor ledAcademy sponsor ledCity technology collegeCommunity schoolCommunity special schoolFoundation schoolFoundation special schoolFree schoolsFree schools 16 to 19Free schools alternative provisionFree schools specialLocal authority nursery schoolNon-maintained special schoolPupil referral unitStudio schoolsUniversity technical collegeVoluntary aided schoolVoluntary controlled schoolGET /codes/attendanceReturns a list of attendance codes that will be accepted in attendance submissionsIf successful, this returns an AttendanceCodes list2540421640"AttendanceCodes" : [{"attendanceCode" : "string""description" : "string"}]020000"AttendanceCodes" : [{"attendanceCode" : "string""description" : "string"}]Resource RepresentationParameter NameTypeDescriptionattendanceCodeslistThe list of attendance codesattendanceCodestringThe attendance codeInitial possible values are/\BCDEGHIJLMNOPRSTUVWXYZ#descriptionstringDescription of the attendance codeGET /codes/ncyeargroupReturns a map of NC Year Groups that will be accepted in attendance submissionsIf successful, this returns an NCYearGroups list2540424815" NCYearGroups " : [{"code" : "string""description" : "string"}]020000" NCYearGroups " : [{"code" : "string""description" : "string"}]Resource RepresentationParameter NameTypeDescriptionNCYearGroupslistThe list of year group codescodestringThe NC Year Group codeInitially this will be limited toE1E2N1N2R1234567891011121314MXdescriptionstringDescription of the NC Year Group code ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download