This guide can be used as a tutorial for uploading a zip containing OneRoster-standarized CSVs without the aid of the user-interface provided by the Gooru's OneRoster application.

Bear in mind that the code we're using to build and make the request is written in Ruby, but it should be easily replicated in another programming language

1. Gather the information

We'll need the following information to build the request

Data	Description
Partner
District
CSV File
User Credentials	These consist of a client id and a client key. A client should have them.

2. Make the request

This is the Ruby code that allows us to make the request that successfully uploads a zip with the csvs and which then proceeds with the migration/exporting of records:

require 'rest_client'

payload = {
      zip_upload: {
        partner: 'Partner Name',
        district: 'District Name',
        filename: File.open('path/to/file_containing_csvs.zip', 'r')
      }
    }
RestClient.post 'https://oneroster.gooru.org/zip_uploads',
                payload,
                {
                  content_type: :json,
                  accept: :json,
                  Authorization: 'Basic ************'
                  }

There are several details that are worth mentioning:

For this code to run, Ruby 2+ is needed. Also, the rest-client gem should be installed (https://github.com/rest-client/rest-client).
Three request headers must be specified:

Header	Value
Content-type	application/json
Accept	application/json
Authorization	`Basic` followed by the base 64 encoded client id and client key. For example, if client id equals `1111` and client key equals `2222`, we'll need to join both values with a `:` in between: `1111:2222`. Then we have to encode them using base 64. This gives `MTExMToyMjIy`. That means that our Authorization header must look like `Basic MTExMToyMjIy`

It may not be evident in the code, so here but the names of the keys of the payload must be: zip_upload[partner], zip_upload[district], zip_upload[filename]
The request must be sent as multipart. In the Ruby example code, the rest-client gem recognizes that a file is present in the payload, and sets multipart true automatically, but in other languages/tools this might need to be specified.

🚧
The request takes too long to complete
Depending on how much your zip file has, and how fast is your Internet connection, this request will take some time to be completed.

🚧
File restriction
The limit on the file size is 200 MB. The file must also be a zip file

3. Handle the response

There are several http codes that might be received in the response:


500	An application error has occurred. There's no more the client can do except perhaps warn warn Gooru of this
404 Not Found	Check the url in the request: it might have been mistyped. Also, check that the HTTP method used in the request is `POST`. If everything is correctly specified and you're still getting `404`, please contact Gooru
401 Unauthorized	Check that you're correctly submitting the `Authorization` header. Check that you are submitting the correct encoded credentials. If you think everything is ok on your end, please contact Gooru
400 Bad Request	Check that your request has ALL of the fields in the payload, and that they have the specified format (`zip_upload[partner]` and so).
422 Validation Error	Check that all of the fields in the request have a value. This differs from `400` because you might have the payload correctly formatted with all the fields, but some field may have no value (For example `zip_upload[district]` might be empty and it shouldn't)
200 OK	This response is the nice one. It should have a body, in JSON, which looks like this: `{"zip_upload": { "id":96, "uuid": "ff9efe89-9b46-4961-b693-525236578994"}}`. This is just information regarding the upload you just did. If you want to view the progress on the migration, you could use the received `uuid` like this: https://oneroster.gooru.org/zip_uploads/<uuid> Where `<uuid>` is the uuid of the zip upload you just did. However, you'll need to use the UI and be logged in to enter the link