Schools holds a lot of data. A municipality holds a lot of students (at the time of this writing Stockholm has 41796 registered gymnasium students, Gothenburg has 23399), and each student gets grades in 10 subjects (just to make it easier to count). Fetching all the grades based on these two examples could potentially mean well over 100 000 grades. The size of one grade weighs about 1Kb, which would mean that the result would be 100 Mb. That's a lot of data to download before being able to parse it. When the client make that request it needs to wait for the entire result to come back before it could handle the data, resulting in that the client times out before it can even get started. You could see it as fetching water from a well. If you need 180 liters of water it's hard to take one big tank to the well by hand, fill it up and drag it back home. Instead you use smaller buckets and run back and forth to the well until you've got everything you need. That's why it's better to use paginated results. How do I paginate our SS12000 data? Paginating our SS12000 data is very easy. Use the query parameter limit in the request (https://api.ist.com/ss12000v2-api/source/SE00100/v2.0/grades?limit=1). That will populate the the attribute pageToken in the response. In this example I'm just using limit=1 but that is obviously just for this example. In a real scenario a suitable page size would be between 1000 and 2000 items. It might be self-explanatory, but how many you should get in a single request all boils down to the size of the item (grades as mentioned above is 1kb per item, so 1000 grades would mean 1Mb per chunk). Personally I would try and stick to around 1Mb. Anyway, the next time I do my request I just use that pageToken as a parameter to get the next page of data. When you have the pageToken you don't need the limit anymore. When you reach the last page of the book (well, rather collection) the pageToken will be empty. That way you know you're done.

The SS12000 specification don't have a pure teacher or student endpoint. So how can you receive a list of teachers? However, the specification do define endpoints for persons working in a school. Each teacher should have an assigned duty, and there is an endpoint for duties. Fetching duties In this guide we'll use Postman to test our requests. You can download and use our Postman collection to easily get started working with educloud in postman. If you're new to postman you can learn how to import it in the "Importing our Postman Collection" guide. Now, to fetch duties we simply make a request to https://api.ist.com/ss12000v2-api/source/SE00100/v2.0/duties. This returns a list of every duty we have. We can see what school / organisation this duty belongs to, when it started and so on. There is also the field dutyRole which defines what kind of work the duty represents. In the API documentation you can see that there is a parameter we can use that lets us filter the results to only include those with the duty role of teacher (and since SS12000 is a swedish standard it's called "lärare"): So what we need to do then is to add dutyRole as a query param, like so: https://api.ist.com/ss12000v2-api/source/SE00100/v2.0/duties?dutyRole=Lärare - Let's try it and see what kind of result we get back: If you compare the two you'll see that the first visible object has changed from "Annan Personal" to "Lärare", meaning that our filter was successful. What about the personal information about the teacher such as first name or their email addresses? In order to get that we need to add one more parameter to our request. Expanding the result with person If we jump back to the documentation one last time we can see that the duties endpoint has another param that we can add to our request, which is the expand key. The expand lets us send in a string or a list of string to expand our request with additional data that the entity we're requesting might hold. In the duty case shown below we have the option to expand on "person" which will include a data from the person entity as an embed. All data that we get by using the expand key will be available via the _embedded key on the response. And that's it! Now we've managed to get all the teachers from a specific customer from SS12000. If you want to filter the data further, such as fetching teachers from a specific school you can use the "organisation" query param as well. If you have any questions regarding this you're most welcome to ask them in the forums.

We have created a postman collection where you easily can get started working with EduCloud. Download Setup First you need to create an environment in Postman. To do that you click on the eye icon in the top right corner which is also known as Environment quick look. Clicking that will open a dropdown that shows your current environment and your global variables. Click "Add" in the Environment section to create a new environment for your Educloud SS12000 collection. Give it an appropiate name, we will use EduCloud - SS12000 Demo in this example. Next step is to set the variables used in the collection found below. The ones we are using are: auth - This will be used as the authentication headers and should not have an initial value. clientIdProd - This is the Client ID you've received either from IST or from your contact. clientSecretProd - This is the Client Secret you've received either from IST or from your contact. clientIdAcceptance - This is the Client ID you've received either from IST or from your contact. clientSecretAppectance - This is the Client Secret you've received either from IST or from your contact. When you've added the variables and set the Initial Value with your real data you need to click Save. When you've done that you'll see that the orange dot in the tab will disappear. Every time you authenticate the request will use the variables defined here to authenticate and then use the authentication type and access token we receive from the request to set the auth variable. Import Postman collection After we've defined our environment it's time to get the so that we can import it into Postman and start making requests. On the left side of Postman you'll see a bunch of icons. Click on the one that looks like a folder (in the screenshots above). That will open up your collections. At the very top of the sidebar you will see the My Workspace and next to it there are two buttons for creating a new collection, or to import one. Click that Import button. If you downloaded the collection, click "Upload files" and choose the one you just downloaded. If you just copied the content of it then go to the "Raw Text" tab and paste the entire JSON. Then choose continue and on the next screen choose "Import". The collection will be called EduCloud - SS12000. Authenticate Now that you've setup the environment and imported the collection you are ready to authenticate. Expand the collection to see the requests and folders within it. Go to Authentication and select the environment you want to authenticate towards by double clicking on it. This will open it up in a new request tab and if you click on the Body tab you can see that the variables we just created is being used. When you click send there is a post send action that will happen that sets the auth variable as explained above and for every request you do after that will use that auth variable to to authenticate the request. After doing so you will automagically be able to do any of the requests in the collection. Let's say that you want to fetch all grades. Just double click on the Grades > Fetch all grades and you're ready to go. Best of luck and if there is anything you're wondering about, just ask in the forums and you'll get the help you need!