Overview

Goal of this RESTful API is to give partners access to our public contents to be integrated in their own products, websites, applications: if you wish to have an authentication token, please contact us.

Authentication headers

In order to authenticate yourself to the service, you need to send an authorized JSON Web Token in the header of your requests for authentication and authorization; find out more at https://jwt.io/.

Should you execute the request with wrong or missing header, you will receive an HTTP Response 401 (Unauthorized).

Our RESTful API is completly stateless so your token must be included in every single request.

Methods, routes, blacklisting and whitelisting are defined at JWT level so depending on the token you are using, you may or may not be able to use a route or a method explained in this documentation.

If you are debugging with Postman API Client, your JWT can be sent as an URL parameter named Authorization with value Bearer[WHITESPACE]<your-JWT-here>.

https://api.tecnoimprese.it/routename?Authorization=Bearer%20eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE0NTQ1NzYwODQsImp0aSI6ImZXS3R2S0NxVXhMQ3UreEZ5cE1hRmtGd2xhdm5zVE1LKzhiUjQ1OXFMa009IiwiaXNzIjoiYXBpLnRlY25vaW1wcmVzZS5pdCIsIm5iZiI6MTQ1NDU3NjA5NCwiZXhwIjoxNDU3MTY4MDk0LCJzY29wZSI6WyJHRVQiXSwicm91dGUiOlsiY2F0YWxvZ3VlIl19.yZzsqZkAxAW5ZqdX0SrWzXHE-l4A-Kc4wV4jVuyJLpiacWFGRHecLRl0CMBKJhXK2L6mfU82-_CwmXj5eCNT-w

JWT issuer

To get a valid JWT you must call the issuer get route passing a "Secret" value. Secret can be passed as a query var or as an header. Response will be a valid JWT that will work in demo mode for 30 days, unless the secret supplied is ment for higher scopes and routes.

Once your JWT is expired or revoked you must issue a new valid JWT in order to keep on using the API.

https://api.tecnoimprese.it/jwt?Secret=YourSuperTicketToGetAJWT

JSON output format

Output of a get route is by default a JSON associative array named data; optionally you can get a metadata array or force output to be JSONP for safe cross-domain requests (see Output controls).

[
  {
    "metadata": {
      "TotalRows": 10,
      "FilteredRows": 2,
      "Count": 2,
      "TotalPage": 2,
      "TotalFilteredPage": 1,
      "PerPage": 5,
      "MaxPerPage": 20,
      "Page": 1,
      "Limit": 20,
      "Offset": 0,
      "MaxRows": 20,
      "Fields": "ID,NameItem",
      "SortFields": "ID,NameItem",
      "FilterFields": "NameItem"
    }
  },
  {
    "data": [
      {
        "ID": 1,
        "NameItem": "First item name"
      },
      {
        "ID": 2,
        "NameItem": "Second item name"
      }
    ]
  }
]

Naming conventions

Param names (keys) and field names are all case sensitive.

Unless differently specified, this API uses CamelCase practice for naming keys and fields to improve human readability (https://en.wikipedia.org/wiki/CamelCase).

For historical reasons, ID (ment as an item identifier) will be always UPPERCASE weather it is used alone (ie. ID=123) or in composed words (ie. IDCatalogue=123) while q (ment as a textual param to search agains text fields) will be always lowercase (ie. q=mytext).

Routes names are all lowercase.

Common GET options

Default list routes

To get the values to be used for filtering append /filters at the end of a list route; filters and sorting can be applied on the filters list as well.

https://api.tecnoimprese.it/routename/filters

To get a two items array (ID, Definition) append /select at the end of a list route. This output differes from the standard output and is not associative and not multidimensional

https://api.tecnoimprese.it/routename/Select

Output Control

By default, data will be returned in a single multidimensional array named "data". To prepend another array named "metadata" that contains informations about fields and counts for that particular route, send a param Metadata=true.

https://api.tecnoimprese.it/routename?Metadata=true

To force the output to be JSONp instead of JSON, use Callback=NameOfCallback and you will get the output wrapped in the NameOfCallback; only valid Javascript names will be accepted as callback.

https://api.tecnoimprese.it/routename?Callback=NameOfCallback

Returned fields

https://api.tecnoimprese.it/routename?Fields=FieldName1,FiledName2,FieldName3

Items visibility

https://api.tecnoimprese.it/routename?Visible=0

Text search

https://api.tecnoimprese.it/routename?q=-text%20to%20search

Filter results

https://api.tecnoimprese.it/routename?
Filter=[alfa_eq_134_AND_[beta_lt_10_OR_gamma_ne_0]_AND_[google_eq_strin_AND_cr_le_10]]

Will be translated to this sql condition:

AND ( (alfa = 134 AND (beta < 10 OR gamma <> 0) AND (google = 'strin' AND cr <= 10))  )

Only valid and allowed filter fileds are allowed (check the default list routes or metadata for the list of fields).

Values to be checked cannot contain sql reserved words or condition will be ignored (ie. alfa_eq_selected will be ignored because it contains select ... sorry, but this is to prevent malicious sql injections).

Sort results

https://api.tecnoimprese.it/routename?Sort=-alfa
https://api.tecnoimprese.it/routename?Sort=default
https://api.tecnoimprese.it/routename?Sort=-FieldName1,FieldName2

Limit results for pagination

https://api.tecnoimprese.it/routename?Page=2&PerPage=10&MaxRows=7

GET routes

/catalogue

Returns a list of the courses defined in the catalogue with category and catalogue each item belongs to:

https://api.tecnoimprese.it/catalogue
"Fields": "
ID,Visible,Name,Slogan,ImageUrl,Color,Hours,
IDCatalogue,NameCatalogue,ColorCatalogue,
IDCategory,NameCategory,ColorCategory
"