Follow

API Basics

See also: API ReferenceSample Code

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.)

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.

PHPUse 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.

PythonFrom 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:

PHPhttp://us3.php.net/manual/en/refs.xml.php

Javascripthttp://www.w3schools.com/Xml/xml_parser.asp

ASP, ASP.NET, and Windows desktop apps: Use a MSXML DOMDocument object

Pythonhttp://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) 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 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.

Was this article helpful?
3 out of 3 found this helpful
Have more questions? Submit a request

0 Comments

Article is closed for comments.