The API allows you to integrate your IT systems with the Dream-Agreements.eu tool, including the ability to create new agreements automatically, as well as downloading transcripts.
The agreement data is exchanged in an easy to handle JSON data format (see JSON schema and a sample file).
For the impatient:
curl -H "Authorization: [Insert your API key here]" https://dream-agreement.eu/api/agreements/123
All requests to the dream-agreement.eu API are be authenticated with a simple API key scheme. Every account in the tool can freely issue any number of API keys.
The HTTP Authorization header will look like this:
Authorization: [Insert your API key here]
You can obtain your API key here (requires login).There is no pre-vetting of accounts to use the API. In case an API key should be revoked, it can also be done at the same place with a single click.
Each agreement created with an API key will become accessible to the the owner of this API key. If you created the API key with your Google account, then any agreements created will become visible to you when you log in to the UI with the same account.
Therefore you have a choice to either create the agreements with an API key already belonging to your exchange coordinator or (soon!) create agreements under a secure account and then notify the relevant persons (with the appropriate roles). You may notify several of your Erasmus coordinators (multiple coordinators can have access to the same agreement) and even the student, depending on your flow.
If you need API keys for testing or development, the developers can just login with their Google account (or a throw-away one) and obtain an API key the same way.
Currently the API is at version 1. Use prefix /v1
The API version number will only incremented if backwards-incompatible changes have been introduced or in case if the semantics or data structure has been sufficiently changed to warrant a new version number. If, for example, some new data have been made available (a new field in the application, perhaps) the version number is not necessarily incremented as long as a client not aware of the changes is not disrupted. Backwards compatibility remains a high priority, but if it has to be broken, the previous API version will remain available (but not indefinitely).
By default, the latest version of the API is used for all requests. If you would like to use a specific API version for your queries, use the following syntax:
GET /api/v1/agreements/123 instead of GET /api/agreements/123
Implications of using the latest version. Simply put, it means that if a certain query is no longer available in the latest version of the API, you will receive an error. The version number literally means the version of the API, not version of a particular API query. For example, if GET /api/something is removed (in favour of something else, perhaps) then all subsequent requests will return an error. To use such a legacy query, you would need to specify the last version of the API where the query still existed, like so: GET /api/v9/something. Similarly, any queries that were not yet available in a certain specified version, will return an error.
So summarise, we would recommend always prefixing all of your queries with the current API version. This guarantees a stable interface. You may always increment the version number to “unlock” new features or go back to a previous version if you prefer. But do not expect the API to do anything “magical”. The version number you specify defines the interface. If you fail to do so, you are on the “bleeding edge”. This might be good for testing, but before you go live, please stabilise the interface on your part.
All resources have numeric ID-s:
The query expects the body of the request to contain a valid JSON agreement document. See JSON schema and a sample file. There is also a relaxed JSON schema that will permit some data to be substituted with empty strings if you do not yet have it. You can choose which schema to validate against (see below).
| Query parameter | Required | Allowable values | Explanation |
|---|---|---|---|
| role | Required | 'Student', 'Sending' or 'Receiving' | You must specify the role that the API key's owner will have in this agreement. |
| schema | Optional | 'Strict' or 'Relaxed' (default) | You can choose to have your data validated by the strict or the relaxed JSON schema. The strict schema expects the JSON document to contain all relevant fields and is actually used when the user saves the agreement in the web UI. The relaxed schema allows you to set empty string values to most of the data that you do not have and make us collect it for you. |
| reference | Optional | String, up to 128 bytes | Any reference data, for example student ID in your information system. |
An example query:
curl -H "Authorization: [API key]" -X POST --data "@/path/to/agreement.json" https://dream-agreement.eu/api/agreements?role=Sending
A successful query returns a 201 Created code and the URL of the created resource in the Location header.
This query returns a simple list of all the agreements that you have access to.
| Query parameter | Required | Allowable values | Explanation |
|---|---|---|---|
| role | Required | Student, Sending or Receiving | You must provide the role of your access as a mandatory filter. |
| academic_year | Required | 2016,2017,.. | You must provide the academic year of the agreements as a mandatory filter. Note that regular users can assign the agreement to a different academic year, therefore you are not guaranteed to be able to find the agreement under the academic year that you created it under. |
Also note that an academic year 2016/17 is represented as 2016, 2017/18 as 2017 etc.
An example query:
curl -H "Authorization: [API key]" https://dream-agreement.eu/api/agreements?academic_year=2017&role=Sending
A successful query returns a 200 OK code.
An example response:
{
"1001": {
"ID": 1001,
"URL": "/api/agreements/1001",
"type": "Studies",
"academic_year": 2017,
"created_at": "2017-08-01T09:43:30+00:00",
"updated_at": "2017-08-01T09:43:30+00:00",
"revision_ID": 777
},
"1002": {
"ID": 1002,
"URL": "/api/agreements/1002",
"type": "Studies",
"academic_year": 2017,
"created_at": "2017-08-01T11:13:44+00:00",
"updated_at": "2017-08-01T11:13:44+00:00",
"revision_ID": 888
}
}
In order to download a the previously created agreement in JSON format, you need to make a GET query to the URL provided in the Location header of the response of the "New agreement" query. You may also substitute the ID for any of the agreements that you have access to. Use the "List agreements" query to see all of your agreements.
This query will return the latest revision of the agreement, after changes made by regular users that you have shared the agreement with. This is especially useful for downloading the transcripts (contained in the "After" sectuion of the agreement) after the completion of the mobility.
An example query:
curl -H "Authorization: [API key]" https://dream-agreement.eu/api/agreements/123
A successful query returns a 200 OK code.
An example response:
{
"ID": 1001,
"URL": "/api/agreements/1001",
"type": "Studies",
"academic_year": 2017,
"created_at": "2017-08-01T09:43:30+00:00",
"updated_at": "2017-08-01T09:43:30+00:00",
"revision_ID": 777,
"document": {
"academic_year": 2017,
"isced": "",
"study_cycle": "",
"student": {
"name": {
"given": "Peter",
"family": "Meter"
},
"email": "[email protected]",
"birth": {
"date": "1985-02-28"
},
"nationality": "EE",
"gender": "M"
},
"sending": {... },
"receiving": { ... },
"before": { ... },
"commitment": [],
"during": { ... },
"after": { ... }
}
}
Removes the agreement from your account. Note that it will be physically deleted once all of the users that have access to it have deleted it as well.
An example query:
curl -H "Authorization: [API key]" -X DELETE https://dream-agreement.eu/api/agreements/123
A successful query returns a 204 No Content code.