Best practices

To use the DreamApply API efficiently, follow the recommendations below. These techniques help optimize performance, reduce network traffic and make integrations with DreamApply more reliable.

Use filter parameters efficiently

Use filtering parameters to limit the amount of returned data. By applying filters, you can retrieve only the records relevant to your use case.

• Filter indicators: Parameters starting with by indicate a filter. For example, byStatuses=Online filters for the Online status.
• Logical OR: Lists in filtering parameters are combined with a logical OR operator. Lists can be comma-separated or space-separated. For example, GET /api/courses?byStatuses=Online,Standby returns courses where the status is either Online or Standby.
• Logical AND: Different filtering parameters are combined with a logical AND operator. For example, GET /api/courses?byStatuses=Online&byTypes=UG returns courses where the status is Online and the type is Undergraduate.

Use the expand parameter

For some collections and resources, the DreamApply API offers the expand parameter. Use it to retrieve related entities in a single request instead of making multiple follow-up requests. expand is especially useful when you need associated data, such as applicant’s trackers, documents or invoices, together with the primary resource.

Use the HEAD request

Before you issue a GET request to retrieve full resource details, use a lightweight HEAD request.

HEAD requests are similar to GET requests but do not return a response body. You can use them to verify that a resource exists, get the resource size or retrieve metadata.

• For collections, use the X-Count response header to see how many items are available.
• For resources, check the response code. The 200 OK response code indicates that the resource exists.

• GET request
• HEAD request

GET https://apply.example.edu/api/institutions

# Response headers
Content-Type: application/json; charset=utf-8
X-Count: 3

# Response body
{
  "1": {
    "id": 1,
    "status": "Online",
    "name": "Munich Institute of Technology",
    "country": "DE",
    "location": "Munich",
    "www": "https://www.mit-munich.de",
    "erasmus": "D MUNCHEN02",
    "address": "Arcisstraße 21\r\n80333 München",
    "vat": "DE123456789",
    "iban": "DE89 3704 0044 0532 0130 00",
    "registration": "HRB 12345",
    "departments": "/api/v3/institutions/1/departments"
  },
  "2": {
    "id": 2,
    "status": "Online",
    "name": "Sorbonne Department of Science",
    "country": "FR",
    "location": "Paris",
    "www": "https://science.sorbonne.fr",
    "erasmus": "F PARIS004",
    "address": "21 Rue de l'École de Médecine\r\n75006 Paris",
    "vat": "FR55987654321",
    "iban": "FR76 3000 6000 0112 3456 7890 123",
    "registration": null,
    "departments": "/api/v3/institutions/2/departments"
  },
  "3": {
    "id": 3,
    "status": "Draft",
    "name": "Nordic Academy of Arts",
    "country": "SE",
    "location": "Stockholm",
    "www": "https://nordic-arts.se",
    "erasmus": null,
    "address": "Skeppsholmen\r\n111 49 Stockholm",
    "vat": null,
    "iban": null,
    "registration": null,
    "departments": "/api/v3/institutions/3/departments"
  }
}

HEAD https://apply.example.edu/api/institutions

# Response headers
Content-Type: application/json; charset=utf-8
X-Count: 3

Use sleep() loops

To avoid hitting the API quota limit, insert a pause between sequential requests using a sleep(n) loop, where n is the number of seconds to wait. Sleep loops help prevent throttling and effectively manage performance.

Cache results

To reduce the number of API requests, cache frequently accessed data locally for a defined period of time. Refresh the cache only when data is likely to have changed. Caching minimizes network traffic and improves the system response times.

Process data using a queue at a fixed rate

When working with large datasets, use a queue to process items at a fixed rate. Schedule tasks at consistent intervals to control throughput and manage system load.

Format JSON responses

When working with API requests that return JSON data, you can pipe the output to a formatter, such as | python -m json.tool. This makes the response easier to analyze and helps with debugging.

Request the latest API version

To access the latest features and capabilities, specify the latest API version in request URIs. For details, see Versioning and changelog and Get the current version.

GET /api/v8/applicants/123/photo

Review version-specific responses

Different API versions may return different responses for the same request. Check the examples in the API reference to understand what each version provides.

For example, see Offers response.