Quickstart

Assumptions:

  1. You have the following credentials (which should have been generated on install or e-mailed to you if you’re using the cloud version):
    1. Your admin username
    2. Your admin password
    3. An app token
  2. You have the following URLs:
    1. The UI URL. In the cloud version, it looks like: http://<yournamehere>.enfix.com/api/v1/
    2. The LRS URL. In the cloud version, it looks like: http://<yournamehere>.enfix.com/api/v1/
  3. You have cURL or an equivalent HTTP fetching tool to run the commands. Some recommendations:
    1. cURL
    2. httpie

Generating a user token

Every request requires two tokens: an app token and a user token. App tokens are meant to live long-term, and only expired when desired. A user token is intended to last for about 24 hours (configurable in full installations), and provides the context for those requests.

Token requests are one of the few traditional POSTs in the system, in case you need to make this request through a traditional browser form, and accepts a username and password. It looks like the following:

curl -X POST -H "App-Token: [APP_TOKEN]" -d "username=[username]&password=[password]" \
    http://<yournamehere>.api.enfix.com/api/v1/token/

Your token return will look like:

{"token": "8031ac4ce22c"}

covering the available endpoints

All of the API endpoints not related to token generation use a standard HTTP REST mechanism, and use the following standard HTTP verbs:

  1. GET - Retrieving a single or list of objects.
  2. POST - Creating a single object.
  3. PUT - Completely replacing a single object.
  4. PATCH - Updating a portion of a single object.
  5. DELETE - Removing a single object.
curl -X GET -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" \
     -H "Content-Type: application/json" \
     http://<yournamehere>.api.enfix.com/api/v1/

Output should look similar to the following:

{
    "_links": {
        "child": [
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/users/",
                "title": "Users"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/groups/",
                "title": "Groups"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/courses/",
                "title": "Courses"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/activity_sessions/",
                "title": "Activity Sessions"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/learning_paths/",
                "title": "Learning Paths"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/roles/",
                "title": "Roles"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/settings/",
                "title": "Settings"
            }
        ],
        "views": [
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/views/user/<string:user_id>/courses_enrolled_in/",
                "title": "User's Enrolled Courses"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/views/user/<string:user_id>/courses_by_status/",
                "title": "User's Courses By Status"
            },
            {
                "href": "http://<yournamehere>.enfix.com/api/v1/views/course/<string:course_id>/users_enrolled_in/",
                "title": "Course's Enrolled Users"
            }
        ]
    }
}

Each of these describes a valid endpoint to go looking for more data. These endpoints are also visible via the API Navigator.

Retrieving a list of users

An API endpoint that provides a list will always end in a trailing slash. For example, this request shows a list of users:

curl -X GET -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" \
     -H "Content-Type: application/json" \
     http://<yournamehere>.api.enfix.com/api/v1/users/

The status code of your request should return a 200. You should receive output similar to the following (pretty-printed for readability via “python -m json.tool”):

[
    {
        "_id": "514143a7bd7a84210c88ca1d",
        "active": true,
        "date_added": "2013-03-17 23:52:26",
        "date_updated": "2013-03-13 23:27:35",
        "email": "bob@bob.com",
        "name": "Bob",
        "roles": [
            "51298e25835fc685850316d2"
        ],
        "username": "bob"
    },
    {
        "_id": "51b1e78dbd7a844089b652a9",
        "active": true,
        "date_updated": "2013-10-16 16:48:54",
        "email": "gav15@gav15.com",
        "name": "George ches",
        "roles": [],
        "username": "gav15"
    },
    {
        "_id": "51b1e833bd7a844089b652aa",
        "active": true,
        "date_updated": "2013-08-25 12:09:56",
        "email": "a@e.com",
        "name": "George ches2",
        "roles": [
            "51298e25835fc685850316d2"
        ],
        "username": "gav163"
    }
]

If you do not receive either the correct status code or a JSON body that looks similar to the above, you will want to review the Debugging API Error Codes documentation.

Retrieving a single user

An API endpoint that provides a single object will never end in a trailing slash, and will generally have a 24-charcter string as the identifier (usually stored in the “_id” field.) The request to fetch a single user from our list above looks like:

curl -X GET -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" \
     -H "Content-Type: application/json" \
     http://<yournamehere>.api.enfix.com/api/v1/users/51b1e833bd7a844089b652aa

The user object should match the object as fetched from the list view, without the additional objects:

{
    "_id": "51b1e833bd7a844089b652aa",
    "active": true,
    "date_updated": "2013-08-25 12:09:56",
    "email": "a@e.com",
    "name": "George ches2",
    "roles": [
        "51298e25835fc685850316d2"
    ],
    "username": "gav163"
}

Creating a user via the API

All user creations are done via the POST verb, and the POST body is expected to be a JSON object of all the fields describing that user. Creations always go to the main endpoint and not to a specific entity, and the endpoint must always end in a URL. An example:

curl -X POST -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" -H "Content-Type: application/json" \
    -d '{"username": "joe", "password": "asdfasdfasdf", "name": "Test User", "email": "joe123@joe.com"}' \
    "http://<yournamehere>.enfix.com/api/v1/users/"

If successful, you will receive a HTTP 204 status, and the response body will contain something similar to:

{
    "resource_url": "http://<yournamehere>.enfix.com/api/v1/users/51b1e78dbd7a844089b652a9/",
    "_id": "51b1e78dbd7a844089b652a9"
}

You can use the get single command from above to fetch the user from the resource_url listed here.

Updating an object

Updating a user can be done in two ways. Both methods require you use the endpoint for a single object.

st, with PUT, you have to send the whole object, and it will completely replace whatever exists:

curl -X PUT -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" -H "Content-Type: application/json" \
    -d '{"username": "joe", "password": "asdfasdfasdf", "name": "Test User 2", "email": "joe124@joe.com"}' \
    "http://<yournamehere>.enfix.com/api/v1/users/51b1e78dbd7a844089b652a9"

If successful, the body will have no content, and the status code will be 204.

If you just want to modify one or a few fields (in our opinion the common use case), you would use PATCH instead. PATCH expects for the data block a JSON object containing only the fields that are changing, and will overlay those onto the base object:

curl -X PUT -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" -H "Content-Type: application/json" \
    -d '{"username": "joe", "password": "asdfasdfasdf", "name": "Test User 2", "email": "joe124@joe.com"}' \
    "http://<yournamehere>.enfix.com/api/v1/users/51b1e78dbd7a844089b652a9"

If successful, the body will have no content, and the status code will be 204.

tering a list

For filtering:

curl -X GET -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" -H "Content-Type: application/json" \
    "http://<yournamehere>.enfix.com/api/v1/users/?q_username__startswith=gav"

Returns:

[
    {
        "_id": "51b1e78dbd7a844089b652a9",
        "active": true,
        "date_updated": "2013-10-16 16:48:54",
        "email": "gav15@gav15.com",
        "name": "George ches",
        "roles": [],
        "username": "gav15"
    },
    {
        "_id": "51b1e833bd7a844089b652aa",
        "active": true,
        "date_updated": "2013-08-25 12:09:56",
        "email": "a@e.com",
        "name": "George ches2",
        "roles": [
            "51298e25835fc685850316d2"
        ],
        "username": "gav163"
    }
]

It’s a URL param, q_<field>=whatever (exact match), or q_<field>__<filtertype>=whatever.

Supported filter types are:

  1. exact - Matches only the exact phrase specified. Implicit if you don’t specify a filter type.
  2. startswith - Acts like “whatever”% or “whatever”.* in SQL/Regex notation, respectively. Matches anything that starts with the specified string.

Embedding just the player

If you want to embed just the player within your existing site, first follow the instructions to create a token for that user via the API. Then, create an iframe to your content with the following URL:

http://<yournamehere>.enfix.com/api/v1/ssla_tt/<course_id>/?username=<username>&token=<token>