Logging in

Logging in; the odd-one-out. Pretty much everything else follows the default of REST + HAL, but the login-flow is as defined by the OAuth 2 framework. Clients use the Client Credentials Grant flow. Clients can log in on behalf of a user using the Authorization Code Grant flow.

Accessing the root-resource anonymously

Looking at the root-resource, you’ll find the token, and authorize- endpoint, which you can use to authorize Users and retrieve Bearer Tokens for both Clients and Users.

curl 'https://api.goabout.com'
 {
   "version" : "x.y.z",
   "_links" : {
     "http://rels.goabout.com/oauth2-authorize" : {
       "href" : "https://auth.goabout.com/authorize"
     },
     "http://rels.goabout.com/oauth2-token" : {
       "href" : "https://auth.goabout.com/token"
     },
     "self" : {
       "href" : "https://api.goabout.com/"
     }
   }
 }

Logging in with client-credentials

Some resources require client-authentication (or higher). The Geocoder resource is an example. To authenticate yourself with the API, you’ll need a Bearer token. You can request it at the oauth2-token endpoint. The location of which you’ll need to retrieve from the root- resource, as described above.

$ curl -d 'grant_type=client_credentials&client_id=[ID]&client_secret=[SECRET]' 'https://auth.goabout.com/token'
{
  "token_type": "bearer",
  "access_token": "UArtDY9Bpo9Whga2mfd7nIK6vENxp2twtnH7RvPC6xj0jy6"
}

Logging in for Users

Other resources specifically need User authentication. Use the Authorization Code Grant flow to let the User authenticate itself against your service. You will get a different Bearer token for a user [1]. (Different from the client Bearer token.)

$ curl -v -d 'client_id=[ID]&redirect_uri=[REDIRECT_URL]&response_type=code' 'https://auth.goabout.com/authorize'
[... SSL HANDSHAKE ...]
> POST /authorize HTTP/1.1
> User-Agent: curl/7.35.0
> Host: auth.goabout.com
> Accept: */*
> Content-Length: 105
> Content-Type: application/x-www-form-urlencoded
>

< HTTP/1.1 302 Moved Temporarily
< Server: nginx/1.6.0
< Date: Thu, 22 May 2014 09:55:17 GMT
< Content-Length: 0
< Location: https://auth.goabout.com/login
< Connection: keep-alive
< Set-Cookie: JSESSIONID=A100A746ED34FC1E5641F898246D1048; Path=/; HttpOnly

You MUST let the browser handle the POST and redirect. This can also be done as a GET request, making it easier to hand over the URL to the browser. You MUST not intercept any traffic between the User and redirected login-page. After the User logs in and confirms it wants to log in at your service, the browser will redirect to the redirect_uri, with code as GET parameter. e.g.:

You SHOULD use https always, for your redirect url.

After you retrieved the temporary code, you can request a Bearer token at the token endpoint, using the authroization_code grant_type.

$ curl -d 'grant_type=authorization_code&redirect_uri=[REDIRECT_URL]&client_id=[ID]&client_secret=[SECRET]&code=PjzPOX' 'https://auth.goabout.com/token'
{
    "access_token": "caQIdBGpI8HVeyJw4TBPdcvdcIdcJ38hihIuIFVqnKUEtwrx",
    "token_type": "bearer"
}
[1]Retrieving the token multiple times MAY result in getting a different token each time. Unused tokens will be invalidated after some time, but have a reasonable long TTL. You can make sure the token is still valid by checking the response form the API root (p:root)

Using the token

Ok, great, so we have retrieved a Bearer token, what now?

Now we send the token along with every request, using an Authorization header.

$ curl -H'Authorization: Bearer A47qDqVLb1WQU75nx96DBs4LTM6wv6P2oqLALoog50teVHm' [URL]

Only resources accessible for the token you send along will be returned inside the _link parameter of the response. You can check which resources you can access by looking at the root-resource. The only resource accessible without a Bearer token is the API root (p:root), which will only reveal the link to the OAuth2 endpoint if accessed anonymously.

Root resource with Client-credentials

With a client-token (i.e. a Bearer token received with client credentials), the root-resource will tell you a lot more about which resources are available to you as a client.

$ curl -s -H 'Authorization: Bearer UArtDY9Bpo9Whga2mfd7nIK6vENxp2twtnH7RvPC6xj0jy6' 'https://api.goabout.com/'
{
  "version": "x.y.z",
  "_links": {
    "self": {
      "href": "https://api.goabout.com/"
    },
    "http://rels.goabout.com/registration": {
      "href": "https://api.goabout.com/registration{/token}",
      "templated": true
    },
    "http://rels.goabout.com/feedback": {
      "href": "https://api.goabout.com/feedback"
    },
    "http://rels.goabout.com/password-reset": {
      "href": "https://api.goabout.com/password-reset{/token}",
      "templated": true
    },
    "http://rels.goabout.com/plan": {
      "href": "https://api.goabout.com/plan"
    },
    "http://rels.goabout.com/current-location": {
      "href": "https://api.goabout.com/location/current/{latitude}/{longitude}",
      "templated": true
    },
    "http://rels.goabout.com/geocoder": {
      "href": "https://api.goabout.com/geocoder/encode{?query,count}",
      "templated": true
    },
    "http://rels.goabout.com/oauth2-token": {
      "href": "https://auth.goabout.com/token"
    },
    "http://rels.goabout.com/oauth2-authorize": {
      "href": "https://auth.goabout.com/authorize"
    }
  }
}

Root resource with User-credentials

More relations are apparent when a User-token is used to request the root-resource. Not only more resources are available, the User-resource is embedded within the Root-resource, for easy access. The User-resource can also be retrieved by following the self-link within the http://rels.goabout.com/authenticated-user relation.

$ curl -H'Authorization: Bearer A47qDqVLb1WQU75nx96DBs4LTM6wv6P2oqLALoog50teVHm' 'https://api.goabout.com/'
{
  "_embedded": {
    "http://rels.goabout.com/authenticated-user": {
      "_links": {
        "http://rels.goabout.com/password": {
          "href": "https://api.goabout.com/user/1/password"
        },
        "http://rels.goabout.com/trips": {
          "href": "https://api.goabout.com/user/1/trips"
        },
        "http://rels.goabout.com/favorite-routes": {
          "href": "https://api.goabout.com/user/1/favorite-routes"
        },
        "self": {
          "href": "https://api.goabout.com/user/1"
        }
      },
      "name": "User1",
      "email": "user@example.com"
    }
  },
  "_links": {
    "http://rels.goabout.com/registration": {
      "templated": true,
      "href": "https://api.goabout.com/registration{/token}"
    },
    "self": {
      "href": "https://api.goabout.com/"
    },
    "http://rels.goabout.com/oauth2-token": {
      "href": "https://auth.goabout.com/token"
    },
    "http://rels.goabout.com/oauth2-authorize": {
      "href": "https://auth.goabout.com/authorize"
    },
    "http://rels.goabout.com/geocoder": {
      "templated": true,
      "href": "https://api.goabout.com/geocoder/encode{?query,count}"
    },
    "http://rels.goabout.com/current-location": {
      "templated": true,
      "href": "https://api.goabout.com/location/current/{latitude}/{longitude}"
    },
    "http://rels.goabout.com/plan": {
      "href": "https://api.goabout.com/plan"
    },
    "http://rels.goabout.com/password-reset": {
      "templated": true,
      "href": "https://api.goabout.com/password-reset{/token}"
    },
    "http://rels.goabout.com/feedback": {
      "href": "https://api.goabout.com/feedback"
    }
  },
  "version": "x.y.z"
}