====== NNELS API v1.x Documentation ======
Version 0.5 used Services and Services Views.\\
Version 1.x uses RESTful framework.\\
\\

===== Current Testing Server =====
|Host|dev.nnels.ca|
|Base Endpoint|api|
|Example|https://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:
<code>
GET /api/
Host: [:current host]
</code>
===== AuthN =====

==== Request Example =====
Use Basic Auth to encode username:pass
<code>
GET /api/login-token HTTP/1.1
Host: dev.nnels.ca
Authorization: Basic dGVzdC1hY2NvdW50Om5vdFJlYWw=
</code>

==== Response structure ====
<code>
{
    "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"
      }
}
</code>
===== 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:
<code>
GET /api/refresh-token/[:refresh_token] HTTP/1.1
Host: dev.nnels.ca
</code>
===== 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 =====
<code>
GET /api/users/me HTTP/1.1
Host: dev.nnels.ca
access-token: [:access-token]
</code>
==== Response structure ====
<code>
{
    "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"
    }
}
</code>

===== BASIC SEARCH =====

==== Keyword Search v1.1 =====
URL-encode keyword string.

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

===== REPO_ITEMS v1.0 =====

==== Specific Repo Item Request example ====
**With node ID (nid)**
<code>
GET /api/v1.0/repo_items/[:nid] HTTP/1.1
Host: dev.nnels.ca
access-token: [:access-token]
</code>

**Alternate load by UUID (uuid)**
<code>
GET /api/v1.0/repo_items/uuid=[:uuid]?loadByFieldName=uuid HTTP/1.1
Host: dev.nnels.ca
access-token: [:access-token]
</code>

==== Response structure ====
<code>
{
    "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"
    }
}
</code>

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