Differences

This shows you the differences between two versions of the page.

--- api:manual [2024/02/11 10:10] – Lauri
+++ api:manual [2024/11/14 16:18] (current) – [List of API calls] Anton
@@ Line 47: / Line 47: @@
 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:
@@ Line 55: / Line 66: @@
   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.
@@ Line 120: / Line 131: @@
 | [[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/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/ID|/api/applicants/ID/trackers/ID]] | A | GET HEAD | Get information about a specific tracker set on an applicant |
@@ Line 132: / Line 145: @@
 | [[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/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/ID|/api/applicants/consents/ID]] | R | GET HEAD | Get information about a specific consent |