ThatJoeMoore/claims.md

## claims.md

      
    Raw
  

              claims.md
            
          
    Proposal

This is a draft proposal for BYU API 'Claims'. This document is non-normative until approved and documented by whoever it is that approves and documents this kind of thing. Feedback is welcome and encouraged.
Things that need to be addressed or refined ("Yaks to shave") are denoted by a yak-like emoji: 🐃. The use of Yaks is blatantly stolen from inspired by SvelteJS.
Overview

Resource-based APIs, such as the University API, work well for fetching data. However, we often need to ask yes/no questions
about a resource, such as "Is this person a full-time student" or "Does this person's Cougar Cash account have enough money to
cover a transaction at a given location?". These questions require a great deal of domain knowledge to answer. While our
consumers could answer these questions themselves using data from our resource-based APIs, this is less than ideal. It requires
consumers to replicate these business rules, which makes it hard to change them and tightly couples consumers to our APIs.
We would like to have a simple, standard way to ask these questions and abstract this logic away. The proposed solution to this
problem has been named 'Claims'.
Claims offer a way for an API to offer a list of questions that consumers can ask.  Each claim may require the consumer to send
some data, and it response with a true/false answer. The request and response formats are standardized across APIs.
URI Structure

APIs which support claims should offer an endpoint called 'claims', like http://example.com/my-api/v1/claims.
An API may support one or more claim types. Consumers may evaluate a claim individually, or may request that multiple claims
be evaluated together.
Claims may be addressed individually using a URL pattern like claims/{claim_type}.
Claim Evaluation

Claims are evaluated by sending a GET request to the appropriate endpoint.
Evaluating Single Claims

A single claim may be evaluated by sending a GET request to the corresponding endpoint.
If an API offers a claim called "full_time_student", the request could be evaluated with this request:
GET /claims/full_time_student

Almost all claims will need some sort of information in order to be processed. This information is called the "Claim Context."
For example, the full_time_student claim needs an identifier of a potential student, which at BYU is called a "BYU ID."
Claim context values are specified using query parameters on the claim request. To specify a byu_id context value for full_time_student,
the relative URL would look like /claims/full_time_student?byu_id=123456789.
Claims may allow multiple values to be specified for a claim. These should be specified in a comma-separated list.
Claims may require one or more context values to be specified.  They may also define optional context values, which may have
defaults. For example, the full_time_student claim could have an optional as_of_date, which would check if a person
was or will be a full time student as of a specified date. This would default to the current date.
Example URL: /claims/full_time_student?byu_id=123456789&as_of_date=2019-01-02.
Evaluating Multiple Claims

Multiple claims are evaluated by sending a GET request to the root /claims endpoint. There is a mandatory parameter, 'claims', which is a comma-separated list of the claims to evaluate. Claim context values can be passed two ways:

For a context value that has the same name and value across multiple claims, just use the name (byu_id=123456789).
For a context value that is specific to a claim, or that has different values for different claims, use Object Notation: full_time_student[byu_id]=123456789

Evaluation Results

Claim endpoints respond with a simple true/false answer, plus metadata about the claim.
Successful Response

If the claim is evaluated successfully, the response will look like this:
{
  "result": true, # or false
  "metadata": {
    "valid_until": "2099-01-01T01:01:01.111Z",
    "🐃": "Metadata format needs to be defined"
  }
}
Error Response

If the claim cannot be evaluated, such as if the caller is not authorized to view the results of the claim, an error should be
returned in a standard format (🐃)
Multiple-claim response

When evaluating multiple claims, each claim must succeed or fail on its own. This is similar to the principles guiding the University API specification.
The response when evaluating multiple claims looks like this:
{
  "full_time_student": {
    "result": true,
    "metadata": {
    }
  },
  "some_other_claim": {
    "result": false,
    "metadata": {
    }
  },
  "metadata": {
    "🐃": "to shave",
    "available_claims": [
      "full_time_student",
      "some_other_claim"
    ]
  }
}
This includes objects for each requested claim, which must match result if the claim were requested individually. Each result
is keyed by the name of the claim. Metadata about the entire set of claims is also returned (format: 🐃).
If a request is made to the /claims endpoint without any requested claims, the response should include the metadata section with a list of all available claims.