NSN API Documentation (v1.0)

The API is available at https://api.nsn.org.uk/v1/

The JWT API is available at https://api.nsn.org.uk/v1/jwt/


Overview

The NSN API allows you to integerate with the NSN database of resources to find support services to help your users


Concepts and data structure

Organisations that provide support are called Resources. Resources are in one or more Topic Categories. Categories have one parent and may have one, none or many child categories. Categories fit within one of the top topic Areas.


Versioning

The API is versioned with a value in the URL (For example: https://api.nsn.org.uk/v1/areas). If you omit the version (For example: https://api.nsn.org.uk/areas) it will respond with the latest version. New versions are created when there are breaking changes added. New field parameters may be added to an existing version, as long as the API remains backwards compatible.


Authentication

There are two ways of authenticating against the API. Either using an API key or by using a JWT. Using an API key is simpler, but can only be done on the backend. Using a JWT is a small amount more work, but allows you to generate a key that can be given to the front end to use.


API Key

You authenticate against the API by including an API key header in the request as x-api-key. Keep this key secure and do not use it in the front end.

Code Samples

Code snippets and samples for you to get started with API Key authentication and API usage.


JWT

If you want to make the requests directly to the API from the front end, you can authentiate using JWT. To do this you should POST to the /v1/jwt endpoint from your backend so as not to reveal your credentials to the public. Include your username and password as a JSON object in the body:

POST /v1/jwt

{
    'username': username,
    'password': password
}

You will receive a JWT IdToken to send to your front end to be used. The token lasts for 1 hour.

As part of the payload you will also receive a RefreshToken that expires after 30 days. To refresh your token you PUT to the /v1/jwt endpoint. Include your token as a json object in the body:

PUT /v1/jwt

{
    'token': RefreshToken
}

Refreshing is optional. You may find it easier to simpler re-authenticate rather than refreshing your token.

Code Samples

Code snippets and samples for you to get started with JWT authentication and API usage.


Endpoints

GET /v1/

Lists all possible endpoints and provides links to support resources. This is available withotu authentication.

GET /v1/dictionary

Dictionary of possible return values for enumerated keys. (For example, lists all the possible return values for support type and location). This is available withotu authentication.

API Key Endpoints

GET /v1/areas

Returns a list of the top level areas.

GET /v1/category/

Returns a list of all categories

GET /v1/category/{id}

Returns details about a particular category.

GET /v1/resource/{id}

Returns details about a particular resource.

GET /v1/search/resource/{query}

Returns resource results for a search term.

GET /v1/search/category/{query}

Returns category results for a search term.

GET /v1/suggest/category/{query}

Returns a basic array of category suggestions for a search term.

GET /v1/suggest/resource/{query}

Returns a basic array of resource suggestions for a search term.


JWT Endpoints

POST /v1/jwt/

Login with your credentials to get a new JWT.

PUT /v1/jwt/

Refresh your JWT.

GET /v1/jwt/areas

Returns a list of the top level areas.

GET /v1/jwt/category/

Returns a list of all categories

GET /v1/jwt/category/{id}

Returns details about a particular category.

GET /v1/jwt/resource/{id}

Returns details about a particular resource.

GET /v1/search/resource/{query}

Returns resource results for a search term.

GET /v1/search/category/{query}

Returns category results for a search term.

GET /v1/suggest/category/{query}

Returns a basic array of category suggestions for a search term.

GET /v1/suggest/resource/{query}

Returns a basic array of resource suggestions for a search term.