<commit_before><commit_msg>Transferring blueprint from apiary.io<commit_after>HOST: https://platform.points.com

--- Loyalty Commerce Platform API v1 ---
---  
<br/>
![Points Logo](https://www.essoextra.com/images/logo_points_com.gif)

# Reference Documentation
## REST API Design Guidelines 
This API is governed by the Points REST API Design Guidelines document.
Found Here: [**Design Guidelines**](https://docs.google.com/a/points.com/document/d/1IralX6vqCs89Icg_1SeC-wjexyd0GEEA2u41EzTXYRo/edit)
<br/>Please ensure you read this document.

## Getting Started Guide
Please read the Getting Started Guide to understand how to use this API Reference.
[**Getting Started Guide**](https://www.github.com/points/voyager/wiki)

## Authorization
All communications with APIs will require HTTPS encryption. 

All applications using this API, are required to obtain a key-pair made up of a private key (a shared secret) and a public key.  
Every request to the platform must signed as described below.  See the Getting Started Guide for details.

##### Signing
API keys are used to generate signed requests which comform to the [OAuth 2.0 MAC Tokens](http://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-02) specification.
Any request not signed using this algorithm, or sent with an invalid signature, will be rejected with a '401 Not Authorized' response.

##### Application Key Metadata
Application Keys will have a number of meta-data associated with it at the time that it is setup.  
Key meta-data will include Production vs. Sandbox and the type of Product Partner.  These 
will be used by the Platform to determine routing of requests (Production vs. Sandbox).

## Authentication
In this version of the platform, authentication for member information will be completed by attaching 
the required member credential information (fluctuates depending on loyalty partner) in the MV call over HTTPS.  
Password or PIN information will immediately be tokenized at the edge of the platform as to safely store of this data in our systems.  
De-tokenization will occur when the data is required to be sent to the appropriate loyalty partner.

## Pagination
Respones that return a result set or list, will return the first 20 results. If a resource explicitly allows, this can
be overidden to return a different number of results. 
The Link Header (RFC 5988) will be used to proceed to the next result set. 
Relation Type ("rev" param should utilize "next" and "prev" to indicate how to follow the links)

## Standard Headers

## Hypermedia
Links to a resource’s state transitions and to related resources can be found in ‘links’ collections. Here’s an example for an application resource:

{
<br>&nbsp;&nbsp;&nbsp;    …
<br>&nbsp;&nbsp;&nbsp;   “links”: {
<br>&nbsp;&nbsp;&nbsp;“self”: {“href”: “http://....”},
<br>&nbsp;&nbsp;&nbsp;“publicKey”: {“href”: “http://...”},
<br>&nbsp;&nbsp;&nbsp;“privateKey”: {“href”: “http://...”}
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}
<br>}


## Error Responses
The platform utilizes standard HTTP Response codes to indicate response results.  
<br>Client errors are communicated in the response using standard HTTP 4xx status codes. Additional information about the error will be included in the response body using the following JSON format:
<br><br>{
<br>&nbsp;&nbsp;&nbsp;“errors”: [
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; “code”: “ERROR_CODE”,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;“description”: “Error description suitable for debugging or logging.”
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;},
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;“code”: “ERROR_CODE”,
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;“description”: “Error description suitable for debugging or logging.”
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;} 
<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;]
<br>}


The value of ‘code’ can be tested programmatically to handle specific error scenarios. The description should not be used programmatically to handle errors, but is suitable for logging or debugging to provide additional information.

Note that any distinct value for ‘code’ could occur multiple times if the same error occurs more than once e.g. validation errors where required fields are missing.

The listing of all these codes can be found at: [Error Responses](https://github.com/points/voyager/wiki/HTTP-Response-Codes)

## Conditional Requests/Optimistic Concurrency
-

## Content & Scheme
All content is in JSON format.  All strings passes to and from the platform must be encoded to UTF-8.
The platform will ignore the 'Accept' header in the request.
<br> All time values are UTC and represented as strings formatted according to [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601).



---

--
/prod-partner - Product Partner Organization
These set of Application resources enable an application to gather 
information about itself.  These resources utilize the application key 
passed along to the resources (except when defined otherwise) as a way of 
identifying the application identification.
--
Searches list of Applications by App Name, Organization, keyId & LP Access
GET /prod-partner/{id}/apps{?apps,org,keyId,lpaccess}
< 200
< Content-Type: application/json; charset=utf-8
< Link: <https://na.platform.points.com/prod-partner/{id}/apps?page=3>, rel="next"; <https://na.platform.points.com/prod-partner/{id}/apps?page=1>, rel="prev";
{
    "results": [ 
        {
            "id": "someId",
            "name": "<NAME>",
            "type": "web",
            "links": "https://na.platform.points.com/prod-partner/{id}/apps/49282939"
        },
        {
            "id": "someId",
            "name": "<NAME>",
            "type": "mobile",
            "links": "https://na.platform.points.com/prod-partner/{id}/apps/9872349178"
        }   
    ]
    "links": {
        "self": {
            "href": "https://na.platform.points.com/prod-partner/{id}/apps{?apps,org,keyId,lpaccess}"
        }
    }
}

Creates an Application
POST /prod-partner/{id}/apps
> Content-Type: application/json; charset=utf-8
{
    "name": "<NAME>",
    "type": "web"
}
< 201
< Location: https://na.platform.points.com/prod-partner/{id}/apps/49282939
{
    "links": {
        "self": {
            "href": "https://na.platform.points.com/prod-partner/{id}/apps/49282939"
        }
    }
}

Provides a set of application information that can be utilized
by the application for various functions.  
If application header key does not match, an alternate response occurs (401).
GET /prod-partner/{id}/apps/{id}
< 200
< Content-Type: application/json; charset=utf-8
{
    "id": "someId",
    "name": "<NAME>",
    "type": "web"
    "currentState": "production",
    "accessibleLoyaltyPrograms": [
    {
        "name": "US Airways",
        "loyaltyProgram": "https://na.platform/points.com/lps/9834701"
    },
    {
        "name": "Global Rewards",
        "loyaltyId": "https://na.platform/points.com/lps/5678"
    }
    ]
    "termsAndConditions": "Long terms and conditions string goes here."
    "links": {
        "self": { 
            "href": "https://na.platform.points.com/prod-partner/{id}/apps/49282939"
        }
    }
}

Create an Application Key
POST /prod-partner/{id}/apps/{id}/keys
> Content-Type: application/json; charset=utf-8
{
    "type": "production",
    "status": "active",
}
< 201
< Location: https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>
{
    "links": {
        "self": {
            "href": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>"
        }
    }
}

Modify an Application Key (Upgrading to production)
PUT /prod-partner/{id}/apps/{id}/keys/{id}
> Content-Type: application/json; charset=utf-8
{
    "type": "production",
    "status": "deactivated"
}
< 201
< Location: https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>
{
    "links": {
        "self": {
            "href": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>"
        }
    }
}

Retrieve details about an App Key
GET /prod-partner/{id}/apps/{id}/keys/{id}
< 200
< Content-Type: application/json; charset=utf-8
{
    "type": "production",
    "status": "active",
    "publicKey": "<KEY>",
    "sharedSecret": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>/SharedSecret"
    "links": {
        "self": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>",
        "app": "https://na.platform.points.com/prod-partner/{id}/apps/49282939"
    }
}

Initiates an email to resend the SharedSecret to Application Owner
GET /prod-partner/{id}/apps/{id}/keys/{id}
< 200
< Content-Type: application/json; charset=utf-8
{
    "links": {
        "keys": {
            "href": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>"
        }
    }
}

Retrieve all keys associted to an App
GET /prod-partner/{id}/apps/{id}/keys
< 201
< Content-Type: application/json; charset=utf-8
< Link: <https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys?page=2>, rel="next"
{
   "results": [
       {
           "keyID": "<KEY>"
           "type": "production"
           "status": "deactivated"
           "link": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/<KEY>"
       },
       {
           "keyID": "<KEY>"
           "type": "sandbox"
           "status": "active"
           "link": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys/458934-234980f-kj234h-kj324kh"
       },
    ],
    "links": {
        "self": {
            "href": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/keys"
        }
    }
}

Details of promotions that are relevant to the Application & Member
GET /prod-partner/{id}/apps/{id}/promotions
< 200
< Content-Type: application/json;charset=utf-8
{ 
    "results": 
    [
        { 
            "loyaltyProgram" : "US Airways", 
            "loyaltyId": "https://na.platform.points.com/lps/1234", 
            "promotions": 
                [
                    { 
                    "promoId": "https://na.platform.points.com/lps/1234/promotions/4x32", 
                    "promoDescription": "Double reward miles!" 
                    },
                    { 
                    "promoId": "https://na.platform.points.com/lps/1234/promotions/38T9", 
                    "promoDescription": "TRIPLE reward miles!" 
                    } 
                ]
        }, 
        {
            "loyaltyProgram" : "Global Rewards",
            "loyaltyId": "https://na.platform.points.com/lps/5678",
            "promotions":
                [
                    {
                    "promoId": "https://na.platform.points.com/lps/5678/promotions/2256",
                    "promoDescription": "25% more points!"
                    }
                ]    
        }
    ],
    "links": {
        "self": {
            "href": "https://na.platform.points.com/prod-partner/{id}/apps/{id}/promotions"
        }
    }
}

--
/lps - Loyalty Programs
The Loyalty Programs set of resources enable an Application to gather 
necessary information about a Loyalty Partner they want to transact against.  
Additionally, an application may need to utilize specific marketing assets 
for a Loyalty Program such as Logos.
--
Search Registered Loyalty Programs
GET /lps{?lps*,partnerName,routing,appID}
< 200
< Content-Type: application/json;charset=utf-8
< Link: <https://na.platform.points.com/lps?page=3>, rel="next"; <https://na.platform.points.com/lps?page=2>,  rel="prev";
{
    "results": [ 
        {
            "id": "someId",
            "name": "US Airways",
            "partnerID": "usar",
            "routing": "pie",
            "domainName": "USAir_PointsCore",
            "links": "https://na.platform.points.com/lps/294857"
        },
        {
            "id": "someId",
            "name": "Wyndham",
            "partnerID": "wynd",
            "routing": "pie",
            "domainName": "Wyndham_PointsCore",
            "links": "https://na.platform.points.com/lps/91284"
        }   
    ],
    "links": {
        "self": {
            "href": "https://na.platform.points.com/lps{?lps*,partnerName,routing,appID}"
        }
    }
}

Register a new LPS in the Platform
POST /lps
> Content-Type:applicaton/json;charset=utf-8
{
    "partnerName": "Wyndham",
    "partnerID": "wynd",
    "routing": "pie",
    "domainName": "Wyndham_PointsCore",
    "routingName": "Wyndham"
}
< 201
< Location: https://na.platform.points.com/lps/14985736
{
    "links": {
        "self": {
            "href": "https://na.platform.points.com/lps/14985736"
        }
    }
}


Returns a list of marketing terms & assets (logos etc.) that the application can use to 
identify the loyalty program within the application.  Also is a set of marketing assets 
for Points (eg. Powered by points logo)  Assets are links to web based resources.
<br>
If an LP is not found, return a 404 not found.

GET /lps/{lpID}
< 200
< Content-Type: application/json;charset=utf-8
{
    "marketing-assets": 
    [
        {
        "_id":"xxxxx1b6",
        "meta":
            {
            "mimetype":"image/jpeg",
            "description":"First Logo",
            "name":"USAirways Logo 1",
            "filename":"http://cms.platform.points.com/lps/1234234/us250w_132h.jpg",
            "asset_type":"LOGO",
            "dimensions":
            {
                "width":"250",
                "height":"132"
            }
        },
        {
        "_id":"a7180fd271296214",
        "meta":
        {
            "mimetype":"image/jpeg",
            "description":"Second Logo",
            "name":"USAirways Logo 2",
            "filename":"http://cms.platform.points.com/lps/1234234/us_ai_335w_150h.jpg",
            "asset_type":"LOGO",
            "dimensions":
            {
                "width":"335",
                "height":"150"
            }
        }
    ]
    "links": {
        "self": {
            "href": "https://na.platform.points.com/lps/{lpID}"
            }
        }
}


List the authentication fields required by a specific Loyalty Program.
<br> If a LP is not found, return a 404.
GET /lps/{lpID}/authentication-requirements
< 200
< Content-Type: application/json;charset=utf-8
{
    "authenticationFields":
    [
        {
            "fieldKey": "member_first_name",
            "name": "<NAME>",
            "description": "Field description"
        },
        {
            "fieldKey": "member_last_name",
            "name": "<NAME>",
            "description": "Field description"
        }
    ]
    "links": {
        "self": {
            "href": "https://na.platform.points.com/lps/{lpID}/authentication-requirements"
        }
        "actions":
        {
            "member-validations": "https://na.platform.points.com/lps/{lpID}/member-validations"
        }
    }
}


Create a Member Validation
</br>If invalid fields are passed, return a 400 (Bad Request)
</br>If LP Service is unavailable for any reason, return a 503 (Service Unavailable)

POST /lps/{lpID}/member-validations
> Content-Type: application/json;charset=utf-8
{
    "firstName": "Daniel",
    "lastName": "Shapiro",
    "email": "<EMAIL>",
    "password": "password",
}
< 201
< Location: https://na.platform.points.com/lps/{lpID}/member-validations/948202349
{
    "expires": "2013-04-11T12:43:00Z",
    "balance": 23000,
    "links": {
        "self": {
            "href": "https://na.platform.points.com/lps/{lpID}/member-validations/948202349"
        }
    }
}

Validate a Member Validation
GET /lps/{lpID}/member-validations/{mvID}
< 200
< Content-Type: application/json;charset=utf-8
{
    "expires": "2013-04-11T12:43:00Z",
    "balance": 23000
    "links": {
        "self": {
            "href": "https://na.platform.points.com/lps/{lpID}/member-validations/948202349"
        }
    }
}

--
/orders Orders - NOT UP TO DATE
--
Create a new order & return the orderID.
POST /orders
> Content-Type: application/json
{
}
< 202
< Content-Type: application/json
{
    "orderID: "/orders/12345"
}

Retrieve Transactions associated with an OrderID
GET /orders/{id}
< 200
< Content-Type: application/json
{
    transactions: [id1,id2,id3,id4]
}

Deduct points from an account.
POST /orders/{id}/points-out
> Content-Type: application/json
{
    "mv": "/lps/12345/member-validations/78348927"
    "currency": "sky"
    "amount": 24300
}
< 202
< Content-Type: application/json
{
    "message": "success."
    "transactionID": "/orders/12345/9293874"
}

Add points to an account.
POST /orders/{id}/points-in
> Content-Type: application/json
{
    "mv": "/lps/12345/member-validations/78348927"
    "currency": "sky"
    "amount": 220
}
< 202
< Content-Type: application/json
{
    "message": "success."
    "transactionId": "/orders/12345/141341341"
}

Perform an AUTH Against a Credit Card
POST /orders/{id}/auth
> Content-Type: application/json
{
    "mv": "/lps/12345/member-validations/78348927"
    "currency": "CAD"
    "amount": 220.34
    "billingInfo": {
        "firstName": "Daniel"
        "lastName": "Shapiro"
        "street": "171 John St."
        "state": "ON"
        "country": "CAN"
        "type": "visa"
        "number": "4563764523789827"
        "exp": "0617"
        "ccv": "431"
    }
}
< 202
< Content-Type: application/json
{
    "message": "success."
    "transactionId": "/orders/12345/3412341235"
}

Perform an CAPTURE Against a Credit Card
POST /orders/{id}/capture
> Content-Type: application/json
{
    "authID": "/orders/12345/3412341235"
}
< 202
< Content-Type: application/json
{
    "message": "success."
    "transactionId": "/orders/12345/349013244"
}

Check the status of a transaction
GET /orders/12345/{id}
< 202
< Content-Type: application/json
{
    "message": "success."
    "started": <DATE>
    "completed": <DATE>
}








{'fraction_non_alphanumeric': 0.15208869974241238, 'fraction_numerical': 0.031078508231604882, 'mean_word_length': 2.7067247820672478, 'pattern_counts': {'":': 181, '<': 103, '<?xml version=': 0, '>': 66, 'https://': 46, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '284788', 'n_tokens_mistral': 6062, 'n_tokens_neox': 5562, 'n_words': 1389}