NNELS API v1.x Documentation

Version 0.5 used Services and Services Views.
Version 1.x uses RESTful framework.

• Authenticate against the <api_endpoint>/login-token/ resource with Basic Authentication to gain access_token
• Bear the access_token for authorization for all other requests before its expiry period.
• Refresh against <api_endpoint>/refresh-token/ with the refresh_token supplied by initial authentication
• If receiving uid 0 back from a specific user request, this means your access token expired.

Discover Resources and their versions

To discover a list of available resources and the latest version for each, issue:

GET /api/
Host: [:current host]

Use Basic Auth to encode username:pass

GET /api/login-token HTTP/1.1
Host: dev.nnels.ca
Authorization: Basic dGVzdC1hY2NvdW50Om5vdFJlYWw=

{
    "data": [
        {
            "access_token": {
                "data": {
                    "type": "text",
                    "required": false
                },
                "info": {
                    "label": "Token",
                    "description": "Authentication token \"token\" property."
                }
            },
            "type": [],
            "expires_in": {
                "data": {
                    "type": "integer",
                    "required": false
                },
                "info": {
                    "label": "Expire",
                    "description": "Authentication token \"expire\" property."
                }
            },
            "refresh_token": {
                "info": {
                    "label": "Refresh token",
                    "description": "Token used to get a new access token once it is expired."
                },
            }
        }
      ],
      "self": {
         "title": "Self",
         "href": "https://dev.nnels.ca/api/login-token"
      }
}

Set access-token header with value for subsequent requests.

After expires_in reaches 0, a new access_token can be requested with:

GET /api/refresh-token/[:refresh_token] HTTP/1.1
Host: dev.nnels.ca

• User can request information about self with users/me
• Administrator can request information about specific users by their ID: v1.1/users/[:id]
• Or a users listing: v1.1/users/

GET /api/users/me HTTP/1.1
Host: dev.nnels.ca
access-token: [:access-token]

{
    "data": [
        {
            "id": {
                "info": {
                    "label": "ID",
                    "description": "Base ID for the entity."
                },
                "data": {
                    "type": "integer",
                    "required": true,
                    "read_only": true,
                    "cardinality": 1
                }
            },
            "label": {
                "info": {
                    "label": "Label",
                    "description": "The label of the resource."
                },
                "data": {
                    "type": "string",
                    "read_only": false,
                    "cardinality": 1,
                    "required": false,
                    "size": 255
                }
            },
            "self": [],
            "mail": {
                "data": {
                    "type": "text",
                    "required": true
                },
                "info": {
                    "label": "Email",
                    "description": "The email address of the user account."
                }
            }
        }
    ],
    "self": {
        "title": "Self",
        "href": "https://dev.nnels.ca/api/v1.0/users/117"
    }
}

URL-encode keyword string.

GET /api/basic_search/[:keyword1]+[:keyword2]+[:keyword3] HTTP/1.1
Host: dev.nnels.ca
Authorization: Basic dGVzdC1hY2NvdW50Om5vdFJlYWw=

With node ID (nid)

GET /api/v1.0/repo_items/[:nid] HTTP/1.1
Host: dev.nnels.ca
access-token: [:access-token]

Alternate load by UUID (uuid)

GET /api/v1.0/repo_items/uuid=[:uuid]?loadByFieldName=uuid HTTP/1.1
Host: dev.nnels.ca
access-token: [:access-token]

{
    "data": [
        {
            "label": {
                "info": {
                    "label": "Label",
                    "description": "The label of the resource."
                },
                "data": {
                    "type": "string",
                    "required": false,
                    "read_only": false,
                    "cardinality": 1,
                    "size": 255
                },
                "form_element": {
                    "type": "textfield",
                    "default_value": "",
                    "placeholder": "",
                    "size": 255,
                    "allowed_values": null,
                    "title": "label",
                    "description": "The label of the resource."
                }
            },
            "creators": {
                "info": {
                    "label": "Creator",
                    "description": ""
                },
                "form_element": {
                    "allowed_values": [],
                    "default_value": null,
                    "type": "text_textfield",
                    "title": "creators"
                }
            },
            "languages": {
                "info": {
                    "label": "Language",
                    "description": ""
                },
                "form_element": {
                    "default_value": [
                        {
                            "value": "eng"
                        }
                    ],
                    "type": "options_buttons",
                    "title": "languages"
                }
            },
            "isbn": {
                "info": {
                    "label": "ISBN",
                    "description": ""
                },
                "form_element": {
                    "allowed_values": [],
                    "default_value": null,
                    "type": "text_textfield",
                    "title": "isbn"
                }
            },
            "uuid": {
                "data": {
                    "type": "text",
                    "required": false
                },
                "info": {
                    "label": "UUID",
                    "description": "The universally unique ID."
                }
            },
            "published_date": {
                "info": {
                    "label": "Date",
                    "description": ""
                },
                "form_element": {
                    "allowed_values": [],
                    "default_value": null,
                    "type": "field_collection_embed",
                    "title": "published_date"
                }
            },
            "file_resources": {
                "data": {
                    "type": "integer",
                    "required": false
                },
                "info": {
                    "label": "Node ID",
                    "description": "The unique ID of the node."
                }
            }
        }
    ],
    "self": {
        "title": "Self",
        "href": "https://dev.nnels.ca/api/v1.0/repo_items/6804"
    }
}

• The file_resources field contains signed S3 URIs to the files available for download for this title. This is excluded from cache and so will be regenerated upon each GET request.
• Issue GET against /repo-items/?range=N for a listing of N repo items.
• Follow root links element for paging URIs (self, first, previous, last, next)