Introduction

Hello and welcome to the ConcourseConnect API for app developers!

This information covers the steps required to use the API Reference.

With this API you'll be able to leverage the users, permissions and data in ConcourseConnect when building your own apps. Let's say your ConcourseConnect server has data for places… your users would be able to browse a list of places nearby and rate them. Or perhaps your server has private collaboration areas, your users would be able to participate with messaging, photo sharing, check-ins and push notifications. These features and more are possible with the API.

The API is intended for app developers who are familiar with network communication. The API uses either JSON or XML to communicate securely over HTTPS. The API can be used with your language of choice across any kind of network attached device.

What Kinds of Things Can Users Do?

• Access public data without a user account (like blogs, wikis, photos, and places)
• Signup, register and login as a user
• Perform location based searches and check-ins
• Post content (like comments, ratings, photos and activity updates)
• Submit geolocated items
• Receive push notifications

Review the API Reference for a complete list.

Getting Started

The ConcourseConnect API includes REST endpoints intended for 3rd party applications to authenticate as a guest or as a registered user in order to interact with the ConcourseConnect back-end server and modules. The API is full-featured and allows users to register and manage their user accounts without the need for the user to use a web site directly.

The backend system will need to be configured for the types of data you will be working with.

When using the API, the developer will need to obtain a unique developer key from the site owner. This key is used for all requests to the server.

Authorization

An app must be properly registered with the ConcourseConnect site by an Administrator. Every request the app makes must include the client's assigned unique id key. This is done either by adding an additional request header, or by appending the URL parameter key=XYZ to the URL. The client platform (iOS, android, etc.) must also be supplied so that the backend push notifications scheme can be configured correctly.

For example, a Javascript XMLHttpRequest object would set:

xhr.setRequestHeader('X-Concursive-Key', 'key=' + authKey);
xhr.setRequestHeader('X-Concursive-Platform', 'ios');

xhr.setRequestHeader('X-Concursive-Model', 'iphone6s');

Authentication

The API is initially used in guest mode so that the user can view guest-level data or proceed to logging in. Most Connect sites allow user registration via the API. Once registered and logged in, the user can interact with available data exposed through the services.

There are two forms of security used for authenticating with the API:

1. SSL - SSL is the basic way to keep communication secure; SSL must be used when accessing the API services
2. Digest authentication - Every request must also use digest authentication. The user’s username and password do not need to be stored on the device as plaintext, instead the information is hashed either for storage or before transmission

The API is accessed by appending /api to the ConcourseConnect URL.
http://www.example.com/api

When authentication fails, the web server returns error 401: This request requires HTTP authentication () or often a status of 1 in the response instead of 0.

Underlying data has object-level access permissions so not all data returned will be the same for each user.

The services are defined and enabled in Connect’s back-end api/core_services.xml configuration file on the server. This makes it possible to add new custom services and to disable unwanted ones.

Digest authentication requires that the authorization credentials are specified in the HTTP Request Header. See http://en.wikipedia.org/wiki/Digest_access_authentication

Digest username="username",realm="realm",nonce="nonce",uri="uri",response="response"

For example, here are some sample values that are set in the Digest Request Header:

realm = "ConcourseConnect";
uri = "/api/site";
ha1 = md5HexDigest(username + ":" + realm + ":" + password);
ha2 = md5HexDigest("POST:" + uri);
nonce = new Date().getTime();
response = md5HexDigest(ha1 + ":" + nonce + ":" + ha2);

The client can store the ha1 value and the actual username, the password must not be stored. The client will use various URIs depending on the service being accessed. The “site” service above returns information about the site. Use POST/GET for the method as required by the api services.

The server may inspect nonce attributes submitted by clients, to prevent replay attacks.

Data Format

The client application specifies which format the server's response will be in by specifying either format=json or format=xml (the default) as a URL parameter.

API Use Cases

Guest authentication can be used until a valid response has been obtained using user credentials. At that point the user information is stored by the client for future use. If the API ever returns an error, it may be possible that the user information is no longer valid and the user should try logging in again.

The first time the app starts up, the app must access the main site service (to get user data, image and permissions) and then also optionally retrieves some dynamic content to show the user. At some point the app may request push notification access and then that information is sent to the server too.

GET /api/site?format=json&deviceId=X

GET /api/wiki?format=json&profile=main-profile&subject=Mobile+Participation

Display the ‘html’ value of the result set

The user fills out a form and registers

POST /api/registration

The user fills out the login form, the authentication is tested by getting the site and user information:

GET /api/site?format=json

An example of the app retrieving a list of records… like available topics…

GET /api/profileList?format=json&category=Topics

API Reference

Now that you know how the API is used within your applications, let's look at the API Reference for specific uses.