Created by lissensj on May 21, 2014

About the Qeo Root Resource

The Qeo Root Resource provides a list of all services provided by the Qeo Security Management Server. For each service, it lists the corresponding entry point URL(s).

Currently it lists the following services:

  • PKI: to issue certificates based on SCEP.
  • Location: to register a forwarder and retrieve a list of forwarders.
  • Policy: to retrieve a policy file and to check whether the policy file of a device is still up to date
  • Management: a REST API to manage realms, users and devices
  • OAuth: the Qeo OAuth server to provide access to the Rest API
    • Authorization endpoint: used by client to retrieve OpenID selection screen
    • Token endpoint: used by the client to exchange an authorization grant for an access token
  • UI: the Web UI on top of the REST API

Each service can have a self link (representing the service resource itself, that might return a list of entry points) and can have a list of entry points. The entry points are URLs that can be used to consume resources provided by that service. By following the link provided by the entry points, a client should be able to access to all resources provided by the service.

Icon

From release 0.20.0 onwards, the root resource is fetched over HTTPS instead of HTTP. Clients using an older version cannot fetch it over HTTPS. Therefore, using the HTTPS links in any of the procedures in this documentation (cfr Management Procedures) will not work. Either manually adapt the URLs to HTTP or upgrade to 0.20.0. We recommend the latter option.

API

Description:Retrieve the Qeo Root Resource.
URL:/
HTTP Method:GET
Request:

HTTP Header

    • Accept: application/json 
    • If-None-Match: hash of cached resource (optional)
Response:

HTTP 200 Success

HTTP Header

    • Content-Type: application/application+json
    • ETag: hash of resource (optional)
    • Cache directive: the time is second the result should be cached (optional)

Body

The list of Qeo services with corresponding entry point URL:

 

{
  "href" : "http://join.qeo.org/",
  "PKI" : {
    "scep" : {
      "href" : "https://join.qeo.org:8442/ra/scep/pkiclient.exe"
    }
  },
  "location" : {
    "forwarders" : {
      "href" : "https://join.qeo.org:8443/pull/forwarders"
    }
  },
  "policy" : {
    "check" : {
      "href" : "http://join.qeo.org/pull/checkpolicy"
    },
    "pull" : {
      "href" : "https://join.qeo.org:8443/pull/policy"
    }
  },
  "oauth" : {
    "token" : {
      "href" : "https://oauth.qeo.org/v1/token"
    },
    "authorization" : {
      "href" : "https://oauth.qeo.org/oauth2/authorize"
    }
  },
  "management" : {
    "href" : "https://join.qeo.org:8442/qeo-rest-service"
  },
  "ui" : {
    "href" : "https://my.qeo.org/"
  }
}

 

HTTP 304 Not Modified

If the resource match the If-None-Match header.

Root Resource Format

Qeo

The Qeo Root Resource represent all the service provided by Qeo cloud to Qeo devices and users. The Qeo Root Resource has a self reference (href property) and contains one property per service. The property name corresponds to the name of the service.

Service

Each service can be either a link to the resource representing the service or be the embedded resource representing the service. A service resource can have a self reference (not mandatory) and have a list of entry points (generally the first resources you need to access when consuming a service). These entry points are links. A service can have a deprecation marking that the service is deprecated. Extra information, specific to the service can be present.

A link will be an object that contains at minimum an href property with the URL of the link. The relation of the link is the name of the link object.

Forward compatibility

Clients consuming the Qeo Root Resource should be able to handle new properties, services and end points. If it encounters a service or an end point it doesn't know about, it should not take it into account. This way new services can be added without the need for each client to be updated. Clients will still need to be updated client to consume the new services.

Deprecation and removal

Client should be aware to the fact that a service or an end point can be marked as deprecated and removed. Clients should gracefully degrade its behaviour and inform the user. When a service or a link is marked as deprecated, the client should try to use another service/end point to perform the same operation. If the deprecated service or end point is used, the user should be warn is some way as the operation is not done in the most efficient way and it may not be possible to perform the operation in the future without client upgrade.

When a service or end point aren't present any more, the client should give an error to the user in a grace full way without impacting the other functionality. In a GUI, the application should first check if the operation is still possible (via known link) before displaying the GUI element triggering the operation.