Problem Statement
To ensure compatibility and to take advantage of improvements, all API consumers using OpenApply's Public API Version 1 (V1) need to migrate to Version 3 (V3) as soon as possible. Alternatively, the API tokens for V1 can be deleted.
Benefits of Migrating to V3
Upgrading to V3 provides several key advantages:
- Expanded Data Access: V3 includes all student custom fields in API responses, whereas V1 only includes fields present on the application form.
- Improved Performance. Clients can specify which fields to include in responses using the field mask parameter, reducing unnecessary data transfer.
- New Endpoints: V3 introduces additional endpoints for parents, events, contacts, and fees, expanding functionality.
Immediate Changes to V1
To encourage migration, we are actively winding down V1 by implementing the following restrictions:
- Lower Rate Limits: V1 requests will have stricter rate limits compared to V3.
- Daily Quotas: Limits will be imposed on the number of requests that can be made per day
- Reduced Record Returns: The number of records returned per request will be decreased.
How to Migrate
Migrating to Version 3 does not require significant refactoring of code. It necessary steps include:
- Navigate to OpenApply's API manager and create a new V3 credential. Please find steps in this article, which also demonstrates how to setup Postman.
- Use the Client ID and Client Secret to obtain a bearer token from a response to the /oauth/token endpoint.
- Change authentication used in V1 (adding API token) to use a bearer token instead. The bearer token should be placed into a request's `Authorization` header with prefix `Bearer `, a space, and the token.
- Change the path from `v1` to `v3`
Example code for how to obtain a bearer token and add it to the request headers can be found in OpenApply's V3 documentation, available in the "Prerequisites" section via Settings -> Integrations -> Public API -> API Documentation
Summary
| V1 | V3 | |
|---|---|---|
| Authentication | Uses API Token, passed either as query parameter or header | Uses Oauth2 flow |
| Student fields | Same structure, but custom fields are limited to those in the application form only | Same structure, but includes all custom fields from all forms |
| Parent fields | Not available | Available, as well as many other endpoints. |
| Additional endpoints | Not available | Includes parents, events, fees, contacts, and new endpoints will be added to V3, not V1. |
If you need more specific guidance, please consider reaching out to our Integrations Product Director Adam Morris:
: