Legacy API Basics

Make sure to follow the API forums so you're informed about changes and updates as soon as we post them! Just go to the API forum page or Developer announcements page and click the Follow button.

Notice

This API is now deprecated and will receive no further development or improvements, except for security updates.

Please use our new improved API instead at https://populi.co/api.

Introduction

Populi's API allows college developers to make HTTPS requests to Populi in order to retrieve or update information. Requests can be either HTTPS “GET” or “POST”, and Populi will respond with XML data (or in a few cases like file downloads, raw binary data will be returned).

Security

You should take care to secure all applications that use the Populi API. If any of your applications are breached, it will likely lead to compromising the Populi account used by the application and possibly other accounts as well. Populi cannot be held responsible for security breaches or data loss resulting from misuse of the API. See the Terms of Service for details.

Using the Populi API through your own applications can create a security risk if your applications are not secure. To minimize that risk, follow these guidelines:

Do not store Populi username/passwords in the source code of your applications, if at all possible — especially for applications that run on shared workstations or desktop PCs. (And, obviously, never hard-code passwords or access keys in client-side code like Javascript). Instead, ask end users to input their credentials each time they need to generate a new access key. You can store access keys in applications that run on a secure server.
Make sure that your applications' source code is secure from unauthorized access. If someone were able to view or change your applications' source code (specifically its cached access key or hard-coded password), they could easily gain access to Populi.
Create limited Populi user accounts specifically for API access. Only give these accounts the minimum required access privileges they need to do their jobs. (For example, if you have a web script that generates a dynamic college directory, that script's API account does not need to belong to the Academic Admin group—one with Staff group privileges would suffice.)

Rate limiting

The API enforces rate-limited in order to stay responsive for all users. The rate limits are as follows:

3AM - 7PM (Pacific Standard Time): 50 requests per minute per API user.
7PM - 3AM (Pacific Standard Time): 100 requests per minute per API user.
There will be additional limits for certain high-intensity API calls, as well as per-IP and per-college limits.

If you pass your limit, Populi will return HTTP response code 429 (Too Many Requests).

Handling 429 response codes by exponentially backing off

If your app exceeds its rate limit, you should pause for just over a minute before sending additional requests (that way you'll be guaranteed that the timer has been re-set). However, it's much more efficient to design your app to stay below the limit and avoid 429 responses altogether! You could do this by placing a small delay between calls.

If your app is making API requests from multiple threads, you'll need to make sure all threads are backing off when receiving 429 responses.

Best practices to avoid 429 responses in the first place

We recommend the following practices to reduce interruptions and provide the best experience:

Avoid constant polling.
Add a small delay between rapid API calls.
Cache your own data when you need to store specialized values or rapidly query large data sets.
Only pull the data you need (e.g., set get Updated People, get Updated Enrollment, get Tagged People, etc.).

Language-Specific Basics

Whatever language you use to write your application, you'll need to know how to do basically two things in order to use the Populi API: Send HTTPS requests and Parse XML responses.

Sending HTTP Requests

Populi API calls are made through HTTPS. Here are some online guides for making HTTPS requests in various programming languages.

PHP: Use the PEAR library module HTTP_Request; with PECL, you can use the HttpRequest class.
Javascript (client side):the XMLHttpRequest object(remember not to store authentication information in client-side scripts!)
Classic ASP and ASP.NET (server-side): Create and use a ServerXMLHTTP object in VBScript, JScript, or your chosen .NET language.
Windows PCs: Create an XMLHTTPRequest object using the language of your choice.
Python:From the "Dive Into Python" online book

Parsing XML

Populi responses to API calls are in XML. The easiest way to handle XML is to use a XML handling library for your programming language. Here are some links to some libraries for common languages:

PHP: http://us3.php.net/manual/en/refs.xml.php
Javascript: http://www.w3schools.com/Xml/xml_parser.asp
ASP, ASP.NET, and Windows desktop apps: Use a MSXML DOMDocument object
Python: http://www.diveintopython.org/xml_processing/index.html

Caching

We highly recommend that Populi API users create a local cache of data they have retrieved from Populi, especially if it contains data that will not change often (such as the course catalog or faculty/staff directory) but will be accessed often (such as a publicly accessible web page). >Accessing a local cache will be much faster than constantly contacting the Populi for data that is unlikely to have changed.

If you are integrating Populi data into a web content management system (CMS), you can check to see if the system itself already supports caching. In this case, it could serve up the relevant page's HTML instead of executing the dynamic page code, and you won't have to do any extra work yourself. Consult your CMS's documentation to learn whether this is possible.

Authentication

Before performing any requests, your application needs to authenticate and obtain an access key. For this, you need a Populi user account that has the necessary privileges to access the information you'll be requesting. An access key is associated with the account used to create it, and it remains valid until the password of the corresponding account is changed. This allows the API to be stateless; i.e., it does not require session management via “cookies”. This also means that you can generate an access key once and hard-code it into your application, which is better than hard-coding a password (since if your source code is compromised the access key cannot be used to log into the Populi web interface, and once you're aware of the breach you can immediately change your password to invalidate the access key).

Access Key Request Structure

To get an access key, send a HTTPS POST request (we do not allow GET, since that could result in your password being stored in Populi server logs) to https://yourcollege.populiweb.com/api/(replacing yourcollege with your college's actual Populi subdomain and keeping the trailing slash at the end of the URL) with the following parameters:

Param Name	Values	Required?
username	e.g. bob.programmer	Yes
password	the password for the user name above	Yes
account_type	Reserved for future versions; currently unused

If you have more than 15 failed login attempts in an hour, Populi will block your account for security reasons. The account will need to be re-enabled by an Admin user in the Populi web interface.

Never store your API access key in an insecure place. If you have reason to believe your key has been compromised, use the Populi interface to change the password of the associated account, then generate a new key.

Access Key Response Structure

Example of a successful access key response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<access_key>
		32AD2d3432...REALLYLONGSTRINGOFCHARACTERS...232as72asdf3
	</access_key>
	<account_id>
		<id>2222</id>
	</account_id>
	<account_type>PERSON</account_type>
</response>

The accountid is the same as the Populi personID of the account. The accounttype element could be either “PERSON” or “ROBOT”. Currently “ROBOT” is unused.

Using the Access Key

All API requests (GET or POST) must include either the access_key as the Authorization header or the parameter access_key, the value of which needs to be a valid access key obtained using the request described above.

Parsing Responses

Assuming no HTTP errors, all requests will return a UTF-8-encoded XML document with a root node of either error or response. The successful responses documented below should be assumed to be wrapped in a response element, whose child elements vary with the request, and which may also be empty.

Successful Response Example

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<prospect_source>
		<id>1111</id>
		<name>Admissions Poster at Conference</name>
		<type>ADVERTISEMENT</type>
	</prospect_source>
	<prospect_source>
		<id>2222</id>
		<name>Datatel 2010 Prospect List #1</name>
		<type>PURCHASED</type>
	</prospect_source>
	...
</response>

Error Example

<?xml version="1.0" encoding="UTF-8"?>
<error>
	<code>AUTHENTICATION_ERROR</code>
	<message>Malformed access key</message>
</error>

The error element will always have the sub-elements code and message. Error codes are actually strings, not numbers, and will be one of the following:

Code	Meaning
AUTHENTICATION_ERROR	Authentication error; wrong username/password (if requesting access key) or invalid access key (other requests).
UKNOWN_TASK	You're calling a 'task' that doesn't exist.
BAD_PARAMETER	Bad parameter; a missing parameter or invalid parameter value.
LOCKED_OUT	The account is blocked (usually as a result of too many failed logins). In response to 'getMyAcademicStats' it can also mean that the student's grades are withheld.
PERMISSIONS_ERROR	Security error; either the account does not have sufficient permissions to perform the request, or sent a suspicious request that triggered some other type of security warning. Use an account with higher privileges to perform this task (having the Staff role is usually enough).
OTHER_ERROR	A general error code meaning that Populi could not complete the request as specified (often caused by using a nonexistent person ID, academic term ID, etc.). If you cannot figure out why you keep getting this error, contact Populi customer support.

Getting started

Now that you understand the basics, check out the API Reference to see all the tasks you can perform via the API. The easiest way to get started (if you're using PHP) is by downloading some Sample Code.

The Postman tool is helpful for initially experimenting with the Populi API. In Postman, the access key request and response would look something like the following image.

Using the Authorization header in Postman would look like this:

Using the access key parameter, an API call in Postman would look like this:

Make sure to follow the API forums so you're informed about changes and updates as soon as we post them! Just go to the API forum page or Developer announcements page and click the Follow button.