| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| api:manual [2024/01/23 19:17] – [List of API calls] Lauri | api:manual [2024/11/14 16:18] (current) – [List of API calls] Anton |
|---|
| 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). | 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: | Currently supported API versions: |
| |
| GET /api/v2/applicants/123/photo | ^ Version ^ Status ^ |
| | | 1 | Deprecated | |
| | | 2 | Deprecated | |
| | | 3 | Supported (default *) | |
| | | 4 | Supported | |
| | | 5 | Supported (latest, recommended) | |
| | |
| | * By default, version 3 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/v3/applicants/123/photo |
| |
| If the version number is omitted, the latest version of the API is used: | If the version number is omitted, the latest version of the API is used: |
| GET /api/applicants/123/photo | GET /api/applicants/123/photo |
| | |
| 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. | 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/v2/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. | **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. |
| | [[api:/api/applicants/ID/emails|/api/applicants/ID/emails]] | C | GET HEAD | Get a list of emails that are sent to an applicant | | | [[api:/api/applicants/ID/emails|/api/applicants/ID/emails]] | C | GET HEAD | Get a list of emails that are sent to an applicant | |
| | [[api:/api/applicants/ID/emails/ID|/api/applicants/ID/emails/ID]] | A | GET HEAD | Get information about a specific emails sent to an applicant | | | [[api:/api/applicants/ID/emails/ID|/api/applicants/ID/emails/ID]] | A | GET HEAD | Get information about a specific emails sent to an applicant | |
| | | [[api:/api/applicants/ID/emails/ID/attachments|/api/applicants/ID/emails/ID/attachments]] | C | GET HEAD | Get a list of attachments of an email | |
| | | [[api:/api/applicants/ID/emails/ID/attachments/ID|/api/applicants/ID/emails/ID/attachments/ID]] | A | GET HEAD | Download a specific attachment (binary data) | |
| | [[api:/api/applicants/ID/trackers|/api/applicants/ID/trackers]] | C | GET HEAD | Get a list of tracker associations | | | [[api:/api/applicants/ID/trackers|/api/applicants/ID/trackers]] | C | GET HEAD | Get a list of tracker associations | |
| | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | GET HEAD | Get information about a specific tracker set on an applicant | | | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | GET HEAD | Get information about a specific tracker set on an applicant | |
| | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | PUT | Set a tracker code to the applicant in question | | | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | PUT | Set a tracker code to the applicant in question | |
| | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | DELETE | Remove the tracker code from the applicant in question | | | [[api:/api/applicants/ID/trackers/ID|/api/applicants/ID/trackers/ID]] | A | DELETE | Remove the tracker code from the applicant in question | |
| | [[api:/api/applicants/ID/studyplans|/api/applicants/ID/studyplans]] | C | GET HEAD | Get a list of study plans created by this applicant | | |
| | [[api:/api/applicants/ID/studyplans/ID|/api/applicants/ID/studyplans/ID]] | R | GET HEAD | Get a specific study plan created by this applicant | | |
| | [[api:/api/applicants/ID/invoices|/api/applicants/ID/invoices]] | C | GET HEAD | List invoices for this applicant | | | [[api:/api/applicants/ID/invoices|/api/applicants/ID/invoices]] | C | GET HEAD | List invoices for this applicant | |
| | [[api:/api/applicants/ID/invoices/ID|/api/applicants/ID/invoices/ID]] | R | GET HEAD | Get information about an applicant invoice | | | [[api:/api/applicants/ID/invoices/ID|/api/applicants/ID/invoices/ID]] | R | GET HEAD | Get information about an applicant invoice | |
| | [[api:/api/applicants/ID/reference|/api/applicants/ID/reference]] | R | GET HEAD | Get the reference code for this applicant | | | [[api:/api/applicants/ID/reference|/api/applicants/ID/reference]] | R | GET HEAD | Get the reference code for this applicant | |
| | [[api:/api/applicants/ID/reference|/api/applicants/ID/reference]] | R | PUT | Store a new reference code for this applicant | | | [[api:/api/applicants/ID/reference|/api/applicants/ID/reference]] | R | PUT | Store a new reference code for this applicant | |
| | | [[api:/api/applicants/ID/matriculation|/api/applicants/ID/matriculation]] | R | GET HEAD | Get the matriculation number for this applicant | |
| | | [[api:/api/applicants/ID/matriculation|/api/applicants/ID/matriculation]] | R | PUT | Store a new matriculation number for this applicant | |
| | [[api:/api/applicants/consents|/api/applicants/consents]] | C | GET HEAD | Get a list of all consents | | | [[api:/api/applicants/consents|/api/applicants/consents]] | C | GET HEAD | Get a list of all consents | |
| | [[api:/api/applicants/consents/ID|/api/applicants/consents/ID]] | R | GET HEAD | Get information about a specific consent | | | [[api:/api/applicants/consents/ID|/api/applicants/consents/ID]] | R | GET HEAD | Get information about a specific consent | |
| | [[api:/api/applications/ID/documents/ID|/api/applications/ID/documents/ID]] | R | GET HEAD | Get a specific applicant document (binary data) | | | [[api:/api/applications/ID/documents/ID|/api/applications/ID/documents/ID]] | R | GET HEAD | Get a specific applicant document (binary data) | |
| | [[api:/api/applications/ID/scores|/api/applications/ID/scores]] | C | GET HEAD | Get a list of scores for this application | | | [[api:/api/applications/ID/scores|/api/applications/ID/scores]] | C | GET HEAD | Get a list of scores for this application | |
| | [[api:/api/applications/ID/studyplans|/api/applications/ID/studyplans]] | C | GET HEAD | Get a list of study plans attached to this application | | |
| | [[api:/api/applications/ID/studyplans/ID|/api/applications/ID/studyplans/ID]] | R | GET HEAD | Get a specific study plan attached to this application | | |
| | [[api:/api/applications/ID/pdf|/api/applications/ID/pdf]] | C | GET HEAD | Get The PDF printout of this application | | | [[api:/api/applications/ID/pdf|/api/applications/ID/pdf]] | C | GET HEAD | Get The PDF printout of this application | |
| | [[api:/api/applications/ID/invoices|/api/applications/ID/invoices]] | C | GET HEAD | List invoices for this application | | | [[api:/api/applications/ID/invoices|/api/applications/ID/invoices]] | C | GET HEAD | List invoices for this application | |