Count Up API

As part of the PEAFIAMP project, we are supposed to come up with a way to provide the service providers (SP, RP) to find out how many times the service was provided to the entity. Note that I used entity and not identity here. An entity may have any number of identities, some of which may even be anonymous. (Here, anonymous means that the identity is valid only during the session and anyone but the OP cannot correlate the identities.)

Having this kind of capability aids the services to provide more aggressive special offers.

I had a discussion with Roland Hedberg today at the University of Umea and came up with the following:

1. Registration Endpoint Discovery
2. Offer registration API
3. Add Count API
4. Set Count API
5. Count get API
6. Offer deletion API

1. Registration Endpoint Discovery

We have to always bootstrap the process somehow: i.e., get the initial link. If the IdP provides this service, it MUST provide the following JSON at a .well-known/count_up_service. (Note: I am still debating whether I should go with JSON Schema or HAL. Here, I am using extended HAL, adding “method”and  “Authorize” to signify HTTP method and HTTP Authorize header respectively. However, it is trivial to convert it to JSON Schema. The reverse, by the way, is not true – a reason to do it in HAL for the time being.)

{
  "_links":{
    "offer-registration-endpoint":{
      "href":"https://fully.qualified.url/of/offer_registration_endpoint{?offer_name,exp}",
      "method":"POST",
      "templated":true,
      "_properties":{
        "offer_name":{
          "required":true,
          "type":"String",
          "description":"User friendly name of this campaign/offer"
        },
        "exp":{
          "required":true,
          "type":"Datetime",
          "description":"Time expressed in YYYY-MM-DDTHH:MM:SSZ format."
        }
      }
    }
  }
}

2. Offer registration API

One of the basic requirement of the setting up of the “offer” is to register the offer meta-data to the server and obtain the offer identifier.It can be done by HTTPS POSTing the following parameters to the offer registration endpoint.

• offer_name REQUIRED. String that represent a user friendly name of the offer
• exp REQUIRED. Date and time representing the timing of the expiry of the offer. e.g., 2013-01-31T00:00:00Z

{
  "_links":{
    "_self"{
      "href":"https://fully.qualified.uri/of/offer_info_endpoint{?offer_id}, 
      "method":"GET",
      "Authorize":Bearer {access_token}"
    },  
    "add_count_endpoint":{
      "href":"https://fully.qualified.uri/of/single_countup_endpoint{?offer_id,id_token,n}",
      "method":"POST",
      "Authorize":"Bearer {access_token}",
      "templated":true,
      "description":"Add n the registered number for the entity that id_token maps.",
      "_properties":{
        "id_token":{"description":"id_token of the user in question."},
        "n":{
           "required":false,
           "type":"integer",
           "description":"A positive or negative integer to be added to the count of the user."
      }, 
    },
    "set_count_endpoint":{
      "href":"https://fully.qualified.uri/of/set_count_endpoint{?offer_id,n}",
      "Authorize":"Bearer {access_token}",
      "templated":true,
      "description":"Set the count for the user to n.", 
      "_properties":{
        "n":{"description":"An integer to which the count for the user is set to."}
      }
    },
    "get_count_endpoint":{
       "href":"https://fully.qualified.url/of/get_count_endpoint{?offer_id,id_token},
       "method":"GET",
       "Authorize":"Bearer {access_token}",
       "templated":true
    },
    "delete_offer_endpoint":{
       "href":"https://fully.qualified.url/of/delete_offer_endpoint{?offer_id},
       "Authorize":"Bearer {access_token}",
       "templated":true
    }
  },
  "offer_id":"string.representing.offer.id",
  "access_token":"string.representing.access.token"
}

Note that this information can always obtained from the URI in “self” relation returned here. It is idempotent.

3. Add count API, 4. Set Count API, 5. Count Get API

These shares the same response. The will let the server to identify the user from the id_token, then applies the operation to the record in the count registry that maps to the core-identifier of the user identified by id_token. For example, in the case of Add count API, it will be like:

SP->Add_EP: offer_id, id_token, n
Add_EP->Add_EP: Map id_token to the core user_id
Add_EP->Add_EP: user_id:count+=n
Add_EP->SP:n

The requests are defined in the response of offer registration API. So, we only need to talk about the response. In every case, the pseudonymous or anonymous user_id in the id_token will be mapped to the core entity id in the count up registry and the operation is applied to the record.

The successful response is the following JSON.

{
  "n":5, 
  "_properties":{
    "n":{"description":"The number of the count after the addition."}
  }
}

An error response would be like:

{
  "error_id":"invalid_token",
  "_properties":
    {
      "enum":["invalid_token","bad_request"]
    }
}

6. Delete Offer API

The final API is the Delete offer API. Again, the request is completely specified in the response stated in section 2., so I will just talk about the response.

Successful response would return HTTP code 200 with the following JSON in the body:

{
  "Status":"successfully deleted", 
  "offer_id":"offer id of the deleted offer"
}

Error resonse would be:

{
  "status":"no_such_offer", 
  "offer_id":"offer id of the deleted offer"
  "_properties":{
    "status":{
      "description":"signifies the status of the response.",
      "enum":["success", "no_such_offer", "bad_request", "invalid_token"]
  }
}