Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
api:manual [2017/11/21 14:25] Safak Samilogluapi:manual [2024/02/11 10:10] (current) Lauri Elevant
Line 38: Line 38:
 That's it! We derive most of the security mechanism from the use of HTTPS, most notably confidentiality (of the API key as well as the data sent and received), integrity (data cannot be altered while "in transit") and mitigation against man-in-the-middle and re-play attacks. That's it! We derive most of the security mechanism from the use of HTTPS, most notably confidentiality (of the API key as well as the data sent and received), integrity (data cannot be altered while "in transit") and mitigation against man-in-the-middle and re-play attacks.
  
 +Here is a quick way to make your first API request:
 +  
 +  curl -v -X GET -H "Authorization: DREAM apikey=\"YOUR-API-KEY\"" https://apply.uni.edu/api/institutions
  
 +On the request above, ''apply.uni.edu'' is the domain for your DreamApply installation. It may also be in the form of "your-uni.dreamapply.com" if you have not yet configured the domain in DreamApply settings. Tip - you can add ''| python -m json.tool'' to the end of the command if you expect to receive JSON data (not all API queries return JSON) to prettify the output.
 ===== Versioning ===== ===== Versioning =====
  
Line 93: Line 97:
   * Filtering parameters themselves, however, will be combined with a logical ''AND'', hence the API calls will only return matching objects that satisfy all of the filters specified.   * Filtering parameters themselves, however, will be combined with a logical ''AND'', hence the API calls will only return matching objects that satisfy all of the filters specified.
  
-  * Typically, any resource ID's (such as the applicant ID 123 in ''api/applicant/123'') are used in object keys in any representations enumerating the resources. For example ''/api/applicants'' will return the collection of applicants as a JSON object with the resource IDs as keys. You would expect to see something like that from ''/api/applicants'':+  * Typically, any resource ID's (such as the applicant ID 123 in ''api/applicants/123'') are used in object keys in any representations enumerating the resources. For example ''/api/applicants'' will return the collection of applicants as a JSON object with the resource IDs as keys. You would expect to see something like that from ''/api/applicants'':
  
   {   {
Line 109: Line 113:
 | [[api:/api/journal|/api/journal]] | C | GET HEAD | List journal events. **Start point for many integrations** :!: | | [[api:/api/journal|/api/journal]] | C | GET HEAD | List journal events. **Start point for many integrations** :!: |
 | [[api:/api/applicants|/api/applicants]] | C | GET HEAD | List applicants using filters set as parameters | | [[api:/api/applicants|/api/applicants]] | C | GET HEAD | List applicants using filters set as parameters |
 +| [[api:/api/applicants|/api/applicants]] | C | POST | Create a new applicant / lead and send welcome letter |
 | [[api:/api/applicants/ID|/api/applicants/ID]] | R | GET HEAD | Return information about an applicant | | [[api:/api/applicants/ID|/api/applicants/ID]] | R | GET HEAD | Return information about an applicant |
 | [[api:/api/applicants/ID/photo|/api/applicants/ID/photo]] | R | GET HEAD | Get the applicant's photo | | [[api:/api/applicants/ID/photo|/api/applicants/ID/photo]] | R | GET HEAD | Get the applicant's photo |
 +| [[api:/api/applicants/ID/consents|/api/applicants/ID/consents]] | C | GET HEAD | Get a list of consents that are associated with an applicant |
 +| [[api:/api/applicants/ID/consents/ID|/api/applicants/ID/consents/ID]] | A | GET HEAD | Get information about a specific consent associated with 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/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/documents|/api/applicants/ID/documents]] | C | GET HEAD | Get a list of documents for the applicant in question | 
-| [[api:/api/applicants/ID/documents/ID|/api/applicants/ID/documents/ID]] | R | GET HEAD | Get a specific applicant document (binary data) | 
-| [[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  |
Line 125: Line 130:
 | [[api:/api/applicants/ID/applications|/api/applicants/ID/applications]] | C | GET HEAD | List applications for this applicant | | [[api:/api/applicants/ID/applications|/api/applicants/ID/applications]] | C | GET HEAD | List applications for this applicant |
 | [[api:/api/applicants/ID/applications/ID|/api/applicants/ID/applications/ID]] | R | GET HEAD | Get information about an applicant application | | [[api:/api/applicants/ID/applications/ID|/api/applicants/ID/applications/ID]] | R | GET HEAD | Get information about an applicant application |
 +| [[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/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 |
Line 131: Line 138:
 | [[api:/api/applicants/trackers/ID|/api/applicants/trackers/ID]] | R | GET HEAD | Get information about a specific tracker | | [[api:/api/applicants/trackers/ID|/api/applicants/trackers/ID]] | R | GET HEAD | Get information about a specific tracker |
 | [[api:/api/applicants/trackers/ID|/api/applicants/trackers/ID]] | R | DELETE | Delete a tracker, removing it from all applicants | | [[api:/api/applicants/trackers/ID|/api/applicants/trackers/ID]] | R | DELETE | Delete a tracker, removing it from all applicants |
 +| [[api:/api/applicants/ID/notes|/api/applicants/ID/notes]] | R | GET HEAD | Get the notes on the applicant |
 +| [[api:/api/applicants/ID/notes|/api/applicants/ID/notes]] | R | PUT | Set the notes box on an applicant card, overwriting existing |
 +| [[api:/api/applicants/ID/notes|/api/applicants/ID/notes]] | R | PATCH | Append to existing applicant notes |
 | [[api:/api/applications|/api/applications]] | C | GET HEAD | Get a list of applications that match the set filtering criterion  | | [[api:/api/applications|/api/applications]] | C | GET HEAD | Get a list of applications that match the set filtering criterion  |
 | [[api:/api/applications/ID|/api/applications/ID]] | R | GET HEAD | Get the application contents (data input by the application).  | | [[api:/api/applications/ID|/api/applications/ID]] | R | GET HEAD | Get the application contents (data input by the application).  |
Line 143: Line 153:
 | [[api:/api/applications/ID/offers/ID/type|/api/applications/ID/offers/ID/type]] | R | GET HEAD | Get the offer type of a specific application offer | | [[api:/api/applications/ID/offers/ID/type|/api/applications/ID/offers/ID/type]] | R | GET HEAD | Get the offer type of a specific application offer |
 | [[api:/api/applications/ID/offers/ID/type|/api/applications/ID/offers/ID/type]] | R | PUT | Set the offer type of the application offer in question | | [[api:/api/applications/ID/offers/ID/type|/api/applications/ID/offers/ID/type]] | R | PUT | Set the offer type of the application offer in question |
 +| [[api:/api/applications/ID/offers/ID/subject|/api/applications/ID/offers/ID/subject]] | R | GET HEAD | Get the subject line of a specific application offer |
 +| [[api:/api/applications/ID/offers/ID/subject|/api/applications/ID/offers/ID/subject]] | R | PUT | Set the subject line of the application offer in question |
 +| [[api:/api/applications/ID/offers/ID/comments|/api/applications/ID/offers/ID/comments]] | R | GET HEAD | Get the offer letter text/comments of a specific application offer |
 +| [[api:/api/applications/ID/offers/ID/comments|/api/applications/ID/offers/ID/comments]] | R | PUT | Set the offer letter text/comments of the application offer in question |
 +| [[api:/api/applications/ID/offers/ID/confirm|/api/applications/ID/offers/ID/confirm]] | R | POST | Confirm an offer |
 +| [[api:/api/applications/ID/offers/ID/decision|/api/applications/ID/offers/ID/decision]] | R | GET HEAD | Get the decision of a specific application offer |
 +| [[api:/api/applications/ID/offers/ID/decision|/api/applications/ID/offers/ID/decision]] | R | PUT | Set the decision of the application offer in question |
 +| [[api:/api/applications/ID/offers/ID/notes|/api/applications/ID/offers/ID/notes]] | R | GET HEAD | Get the notes on the offer |
 +| [[api:/api/applications/ID/offers/ID/notes|/api/applications/ID/offers/ID/notes]] | R | PUT | Set the notes box on an offer, overwriting existing |
 +| [[api:/api/applications/ID/offers/ID/notes|/api/applications/ID/offers/ID/notes]] | R | PATCH | Append to existing offer notes |
 | [[api:/api/applications/ID/offers/ID/score/extra|/api/applications/ID/offers/ID/score/extra]] | R | GET HEAD | Get the extra score of a specific application offer | | [[api:/api/applications/ID/offers/ID/score/extra|/api/applications/ID/offers/ID/score/extra]] | R | GET HEAD | Get the extra score of a specific application offer |
 | [[api:/api/applications/ID/offers/ID/score/extra|/api/applications/ID/offers/ID/score/extra]] | R | PUT | Set the extra score of the application offer in question | | [[api:/api/applications/ID/offers/ID/score/extra|/api/applications/ID/offers/ID/score/extra]] | R | PUT | Set the extra score of the application offer in question |
 +| [[api:/api/applications/ID/offers/ID/score/extra|/api/applications/ID/offers/ID/score/extra]] | R | DELETE | Clear the extra score of the application offer in question |
 | [[api:/api/applications/ID/tasks|/api/applications/ID/tasks]] | C | GET HEAD | List tasks created for this application | | [[api:/api/applications/ID/tasks|/api/applications/ID/tasks]] | C | GET HEAD | List tasks created for this application |
 | [[api:/api/applications/ID/tasks/ID|/api/applications/ID/tasks/ID]] | R | GET HEAD | Get information about a specific application task | | [[api:/api/applications/ID/tasks/ID|/api/applications/ID/tasks/ID]] | R | GET HEAD | Get information about a specific application task |
Line 155: Line 176:
 | [[api:/api/applications/ID/documents|/api/applications/ID/documents]] | C | GET HEAD | Get a list of documents attached to this application | | [[api:/api/applications/ID/documents|/api/applications/ID/documents]] | C | GET HEAD | Get a list of documents attached to this application |
 | [[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/studyplans|/api/applications/ID/studyplans]] | C | GET HEAD | Get a list of study plans attached to 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/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/invoices|/api/applications/ID/invoices]] | C | GET HEAD | List invoices for this application | 
 +| [[api:/api/applications/ID/invoices|/api/applications/ID/invoices]] | C | POST | Create an invoice for this application | 
 +| [[api:/api/applications/ID/invoices/ID|/api/applications/ID/invoices/ID]] | R | GET HEAD | Get information about an application invoice  |
 | [[api:/api/applications/flags|/api/applications/flags]] | C | GET HEAD | Get a list of all flags | | [[api:/api/applications/flags|/api/applications/flags]] | C | GET HEAD | Get a list of all flags |
 | [[api:/api/applications/flags|/api/applications/flags]] | C | POST | Create a new flag  | | [[api:/api/applications/flags|/api/applications/flags]] | C | POST | Create a new flag  |
Line 167: Line 191:
 | [[api:/api/institutions/ID/departments|/api/institutions/ID/departments]] | C | GET HEAD | List departments under the given institution | | [[api:/api/institutions/ID/departments|/api/institutions/ID/departments]] | C | GET HEAD | List departments under the given institution |
 | [[api:/api/institutions/ID/departments/ID|/api/institutions/ID/departments/ID]] | R | GET HEAD | Show information about a given institution department | | [[api:/api/institutions/ID/departments/ID|/api/institutions/ID/departments/ID]] | R | GET HEAD | Show information about a given institution department |
-| [[api:/api/institutions/ID/contacts|/api/institutions/ID/contacts]] | C | GET HEAD | List contact persons under the given institution | 
-| [[api:/api/institutions/ID/contacts/ID|/api/institutions/ID/contacts/ID]] | R | GET HEAD | Show information about a given institution contact person | 
 | [[api:/api/courses|/api/courses]] | C | GET HEAD | List courses using filters set as parameters | | [[api:/api/courses|/api/courses]] | C | GET HEAD | List courses using filters set as parameters |
 +| [[api:/api/courses|/api/courses]] | C | POST | Create a new blank course |
 | [[api:/api/courses/ID|/api/courses/ID]] | R | GET HEAD | More detailed information about a specific course | | [[api:/api/courses/ID|/api/courses/ID]] | R | GET HEAD | More detailed information about a specific course |
 | [[api:/api/intakes|/api/intakes]] | R | GET HEAD | List configured intakes | | [[api:/api/intakes|/api/intakes]] | R | GET HEAD | List configured intakes |
 | [[api:/api/intakes/ID|/api/intakes/ID]] | R | GET HEAD | Get details of a specific intake | | [[api:/api/intakes/ID|/api/intakes/ID]] | R | GET HEAD | Get details of a specific intake |
 | [[api:/api/invoices|/api/invoices]] | C | GET HEAD | List all issued invoices | | [[api:/api/invoices|/api/invoices]] | C | GET HEAD | List all issued invoices |
-| [[api:/api/invoices/ID|/api/invoices/ID]] | R | GET HEAD | Get more information about an invoices |+| [[api:/api/invoices/ID|/api/invoices/ID]] | R | GET HEAD | Get more information about an invoice |
 | [[api:/api/invoices/ID|/api/invoices/ID]] | R | DELETE | Delete an invoice | | [[api:/api/invoices/ID|/api/invoices/ID]] | R | DELETE | Delete an invoice |
-| [[api:/api/invoices/series|/api/invoices/series]] | R | DELETE | List invoice series |+| [[api:/api/invoices/ID/transactions|/api/invoices/ID/transactions]] | C | GET HEAD | List transactions of a specific invoice | 
 +| [[api:/api/invoices/ID/transactions|/api/invoices/ID/transactions]] | C | POST | Create transaction for invoice ("collect invoice") | 
 +| [[api:/api/invoices/ID/transactions/ID|/api/invoices/ID/transactions/ID]] | R | GET HEAD | Get more information about a transaction | 
 +| [[api:/api/invoices/series|/api/invoices/series]] | R | GET HEAD | List invoice series 
 +| [[api:/api/invoices/transactions|/api/invoices/transactions]] | C | GET HEAD | List transactions | 
 +| [[api:/api/invoices/transactions/ID|/api/invoices/transactions/ID]] | R | GET HEAD | Get more information about a transaction |
 | [[api:/api/academic-terms|/api/academic-terms]] | R | GET HEAD | Get a list of all academic terms configured | | [[api:/api/academic-terms|/api/academic-terms]] | R | GET HEAD | Get a list of all academic terms configured |
 | [[api:/api/academic-terms/ID|/api/academic-terms/ID]] | R | GET HEAD | Get information about an academic term | | [[api:/api/academic-terms/ID|/api/academic-terms/ID]] | R | GET HEAD | Get information about an academic term |
Line 186: Line 214:
 | [[api:/api/reports|/api/reports]] | C | GET HEAD | List all reports available | | [[api:/api/reports|/api/reports]] | C | GET HEAD | List all reports available |
 | [[api:/api/reports/ReportName|/api/reports/ReportName]] | R | GET HEAD | Request data from a specific report | | [[api:/api/reports/ReportName|/api/reports/ReportName]] | R | GET HEAD | Request data from a specific report |
 +| [[api:/api/scoresheets|/api/scoresheets]] | C | GET HEAD | List all scoresheets |
 +| [[api:/api/scoresheets/ID|/api/scoresheets/ID]] | R | GET HEAD | Get info about scoresheet |
 +| [[api:/api/scoresheets/ID/scores|/api/scoresheets/ID/scores]] | C | GET HEAD | Get scores |
 +| [[api:/api/scoresheets/ID/scores|/api/scoresheets/ID/scores]] | C | POST | Append an application for scoring |
 +| [[api:/api/scoresheets/ID/scores/ID|/api/scoresheets/ID/scores/ID]] | R | GET HEAD | Get information about a score |
 +| [[api:/api/scoresheets/ID/scores/ID/points|/api/scoresheets/ID/scores/ID/points]] | R | GET HEAD | Get the points of a scoresheet score |
 +| [[api:/api/scoresheets/ID/scores/ID/points|/api/scoresheets/ID/scores/ID/points]] | R | PUT | Set the points of a scoresheet score |
 +| [[api:/api/scoresheets/ID/scores/ID/points|/api/scoresheets/ID/scores/ID/points]] | R | DELETE | Clear the points of a scoresheet score |
 +| [[api:/api/scoresheets/ID/scores/ID/comments|/api/scoresheets/ID/scores/ID/comments]] | R | GET HEAD | Get the comments of a scoresheet score |
 +| [[api:/api/scoresheets/ID/scores/ID/comments|/api/scoresheets/ID/scores/ID/comments]] | R | PUT | Set the comments of a scoresheet score |
 +| [[api:/api/scoresheets/ID/scores/ID/comments|/api/scoresheets/ID/scores/ID/comments]] | R | DELETE | Clear the comments of a scoresheet score |
 | [[api:/api/tableviews|/api/tableviews]] | C | GET HEAD | List all tableviews created with the GUI | | [[api:/api/tableviews|/api/tableviews]] | C | GET HEAD | List all tableviews created with the GUI |
 | [[api:/api/tableviews/ID|/api/tableviews/ID]] | R | GET HEAD | Get more information about a tableview | | [[api:/api/tableviews/ID|/api/tableviews/ID]] | R | GET HEAD | Get more information about a tableview |
 | [[api:/api/tableviews/ID/tabledata|/api/tableviews/ID/tabledata]] | R | GET HEAD | Get the csv data from a tableview | | [[api:/api/tableviews/ID/tabledata|/api/tableviews/ID/tabledata]] | R | GET HEAD | Get the csv data from a tableview |
 +| [[api:/api/administrators|/api/administrators]] | R | GET HEAD | List all administrators in the system |
 +| [[api:/api/administrators/ID|/api/administrators/ID]] | R | GET HEAD | Get information about an administrator |
 +| [[api:/api/ping|/api/ping]] | R | GET HEAD | A dummy call for testing authentication |
  
 ♦ The types are as follows: **C**ollection, **R**esource, **A**ssociation. The latter is an object that represents the relationship between two resources. It is used on one-to-many and many-to-many relationships. However, an association between an applicant and a tracker may carry some information itself, such as the time the association was established. Thus is a special kind of resource. ♦ The types are as follows: **C**ollection, **R**esource, **A**ssociation. The latter is an object that represents the relationship between two resources. It is used on one-to-many and many-to-many relationships. However, an association between an applicant and a tracker may carry some information itself, such as the time the association was established. Thus is a special kind of resource.
Line 212: Line 254:
 ===== Throttling  ===== ===== Throttling  =====
  
-All API calls placed to the same API key are, by default, limited to **60 queries per minute** and **600 queries per hour**. Please note that 60 queries/minute is not the same as 1 query per second, see below.+All API calls placed to the same API key are, by default, limited to **180 queries per minute** and **600 queries per hour**. Please note that 60 queries/minute is not the same as 1 query per second, see below.
  
 If you exceed your API key queries-per-minute quota, you may start to receive ''429 Too Many Requests'' responses. This means that the request was **not** processed and will have to be issued again. If you exceed your API key queries-per-minute quota, you may start to receive ''429 Too Many Requests'' responses. This means that the request was **not** processed and will have to be issued again.