User Tools

mbstring extension must be loaded in order to run mPDF

NNELS API v1.x Documentation

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

Current Testing Server

Hostdev.nnels.ca
Base Endpointapi
Examplehttps://dev.nnels.ca/api/v[:version.minor]/[:resource]/

Notes

  • 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]

AuthN

Request Example

Use Basic Auth to encode username:pass

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

Response structure

{
    "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"
      }
}

AuthZ

Set access-token header with value for subsequent requests.

Refresh Token

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

USERS

  • 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/

User Request example

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

Response structure

{
    "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"
    }
}

Keyword Search v1.1

URL-encode keyword string.

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

REPO_ITEMS v1.0

Specific Repo Item Request example

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]

Response structure

{
    "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"
    }
}

Notes

  • 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)
public/nnels/nnels_api_docs_v1.txt · Last modified: 2019/05/14 10:56 by jonathan.schatz