Private API version (#418)

Adds a version header to the private API, to provide a better experience for any partner that uses our reference implementation as their production PayID server.

The PayID-API-Version header needs to be an ISO8601 date string, of the form YYYY-MM-DD. This is what Coinbase, Stripe, and various other companies use to version their hosted API services.

Note that I kept the /v1/ in the path for the private API. I chose to do this as Coinbase, Stripe, etc. do the same thing. We should never need to increment to /v2/ in the path, but it's cheap to leave it there, makes a smaller diff, and gives us a safety valve for the future.

Author: 0xCLARITY

aws-deploy.md

@@ -46,7 +46,7 @@ You can set up a PayID server on AWS (Amazon Web Services).
 13. Load up your desired PayID to the database using the [private PayID API](readme.md). If you use a subdomain rather than a path, then you must set up a DNS record for the subdomain as described in step 3.
     **Note:** You can add PayIDs for each (payId, network, environment) tuple. Use this cURL command to set up a PayID.
     ```
-    curl --location --request POST 'http://127.0.0.1:8081/v1/users' \
+    curl --location --request POST 'http://127.0.0.1:8081/users' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "payId": "$<your-pay-id-address>",

example/instructions.md

@@ -5,7 +5,7 @@ In this tutorial, we'll be walking through the travel rule handshake protocol
 We'll start off by creating a user:
 
 ```
-curl --location --request POST http://localhost:8081/v1/users --header 'Content-Type: application/json' --data-raw '{
+curl --location --request POST http://localhost:8081/users --header 'Content-Type: application/json' --data-raw '{
   "payId": "$127.0.0.1/exampleUser",
   "addresses": [
   {
@@ -26,13 +26,15 @@ curl --location --request GET 'http://127.0.0.1:8080/exampleUser' --header 'Acce
 ```
 
 We've confirmed that our PayID is working as expected so let's send a payment setup details request:
+
 ```
 curl --location --request GET 'http://127.0.0.1:8080/exampleUser/payment-setup-details' \
 --header 'Accept: application/xrpl-testnet+json' \
 --header 'Content-Type: application/json'
 ```
 
 The returned JSON object is our payment setup details. In this example, the institution is a VASP and has listed any laws that must be complied with in the `complianceRequirements` field of the payment setup details. Specifically, as the originator of the payment we are being asked to comply with the Travel Rule. In order to do that, we'll POST the compliance data to the same URL in order to upgrade our payment setup details object.
+
 ```
 curl --location --request POST 'http://127.0.0.1:8080/exampleUser/payment-setup-details' \
 --header 'Content-Type: application/json' \
@@ -65,8 +67,8 @@ curl --location --request POST 'http://127.0.0.1:8080/exampleUser/payment-setup-
 }'
 ```
 
-
 Upon submission of this data, the beneficiary should identify that we have fulfilled all compliance requirements and send us an upgraded payment setup details object. This upgraded payment setup details cryptographically correlates our submission of compliance data through the complianceHashes field. Now that we have been informed of all compliance requirements, and fulfilled them, we can submit our transaction on ledger and POST back the payment proof.
+
 ```
 curl --location --request POST 'http://127.0.0.1:8080/exampleUser/payment-proofs' \
 --header 'Content-Type: application/json' \

payid-metrics.md

@@ -128,7 +128,7 @@ docker run -it -p 8080:8080 -p 8081:8081 --name payid-server --network payid-net
 Test whether the PayID server is running by creating a PayID with this cURL command.
 
 ```
- curl --location --request POST 'http://127.0.0.1:8081/v1/users' --header 'Content-Type: application/json' --header 'Content-Type: text/plain' --data-raw '{
+ curl --location --request POST 'http://127.0.0.1:8081/users' --header 'Content-Type: application/json' --header 'Content-Type: text/plain' --data-raw '{
      "payId": "alice$127.0.0.1",
      "addresses": [
          {

readme.md

@@ -121,12 +121,12 @@ You can then use the Private PayID API to:
 The private APIs run by default on port 8081. Make sure to adjust this value if needed.
 The list of private endpoints is:
 
-| HTTP Method                              | Endpoint                 |                     Description |
-| ---------------------------------------- | :----------------------- | ------------------------------: |
-| [GET](#421-get-a-payid-user-information) | /v1/users/{user}\${host} |    Get a PayID user information |
-| [POST](#422-create-a-payid-user)         | /v1/users                |             Create a PayID user |
-| [PUT](#423-update-a-payid-user)          | /v1/users/{user}\${host} | Update a PayID user information |
-| [DELETE](#424-delete-a-payid-user)       | /v1/users/{user}\${host} |             Delete a PayID user |
+| HTTP Method                              | Endpoint              |                     Description |
+| ---------------------------------------- | :-------------------- | ------------------------------: |
+| [GET](#421-get-a-payid-user-information) | /users/{user}\${host} |    Get a PayID user information |
+| [POST](#422-create-a-payid-user)         | /users                |             Create a PayID user |
+| [PUT](#423-update-a-payid-user)          | /users/{user}\${host} | Update a PayID user information |
+| [DELETE](#424-delete-a-payid-user)       | /users/{user}\${host} |             Delete a PayID user |
 
 Once you have set up your PayID server, you can access the Private PayID API endpoints using Postman or these cURL commands.
 
@@ -135,7 +135,7 @@ Once you have set up your PayID server, you can access the Private PayID API end
 **Request format**
 
 ```
-GET {pay_id_base_url}/v1/users/{user}${host}
+GET {pay_id_base_url}/users/{user}${host}
 ```
 
 **Path parameters (Required)**
@@ -166,7 +166,7 @@ This operation creates a single user.
 Request (Success)
 
 ```HTTP
-GET http://127.0.0.1:8081/v1/users/bob$127.0.0.1 HTTP/1.1
+GET http://127.0.0.1:8081/users/bob$127.0.0.1 HTTP/1.1
 ```
 
 Response (Success)
@@ -200,7 +200,7 @@ The following table lists the HTTP status codes and messages returned for this m
 **Request format**
 
 ```
-POST {pay_id_base_url}/v1/users
+POST {pay_id_base_url}/users
 ```
 
 **Path parameters (None)**
@@ -251,7 +251,7 @@ Request (Success)
 The addresses array can contain 1 or more objects.
 
 ```HTTP
-POST http://127.0.0.1:8081/v1/users HTTP/1.1
+POST http://127.0.0.1:8081/users HTTP/1.1
 
 {
   "payId": "bob$127.0.0.1",
@@ -297,7 +297,7 @@ You can modify the user information associated with a particular PayID address.
 **Request format**
 
 ```
-PUT {pay_id_base_url}/v1/users/{user}${host}
+PUT {pay_id_base_url}/users/{user}${host}
 ```
 
 **Path parameters (Required)**
@@ -348,7 +348,7 @@ A successful response to the "Update a PayID user" method returns a 201 HTTP sta
 Request (Success)
 
 ```HTTP
-PUT http://127.0.0.1:8081/v1/users/bob$127.0.0.1 HTTP/1.1
+PUT http://127.0.0.1:8081/users/bob$127.0.0.1 HTTP/1.1
 
 {
 	"payId": "bob$127.0.0.1",
@@ -388,7 +388,7 @@ The following table lists the HTTP status codes and messages returned for this m
 **Request format**
 
 ```
-DELETE {pay_id_base_url}/v1/users/{user}${host}
+DELETE {pay_id_base_url}/users/{user}${host}
 ```
 
 **Path parameters (Required)**
@@ -417,7 +417,7 @@ A successful response to the "Delete a PayID user" method returns a 204 HTTP sta
 Request (Success)
 
 ```HTTP
-DELETE http://127.0.0.1:8081/v1/users/bob$127.0.0.1 HTTP/1.1
+DELETE http://127.0.0.1:8081/users/bob$127.0.0.1 HTTP/1.1
 
 {
 	"payId": "bob$127.0.0.1",

src/app.ts

@@ -61,10 +61,7 @@ export default class App {
   }
 
   private launchPrivateAPI(appConfig: typeof config.app): Server {
-    this.privateAPIExpress.use(
-      `${appConfig.privateApiVersion}/users`,
-      privateAPIRouter,
-    )
+    this.privateAPIExpress.use('/users', privateAPIRouter)
     this.privateAPIExpress.use('/metrics', metricsRouter)
 
     return this.privateAPIExpress.listen(appConfig.privateAPIPort, () =>

src/config.ts

@@ -1,8 +1,5 @@
-export enum PrivateApiVersion {
-  V1 = '/v1',
-}
-
 export const payIdServerVersions: readonly string[] = ['0.2']
+export const privateApiVersions: readonly string[] = ['2020-05-28']
 
 /**
  * Application configuration.
@@ -27,7 +24,7 @@ const config = {
     publicAPIPort: Number(process.env.PUBLIC_API_PORT) || 8080,
     privateAPIPort: Number(process.env.PRIVATE_API_PORT) || 8081,
     payIdVersion: payIdServerVersions[payIdServerVersions.length - 1],
-    privateApiVersion: PrivateApiVersion.V1,
+    privateApiVersion: privateApiVersions[privateApiVersions.length - 1],
     logLevel: process.env.LOG_LEVEL ?? 'INFO',
     httpsRequired: process.env.HTTPS_REQUIRED === 'true',
   },

src/middlewares/checkPrivateApiVersionHeaders.ts

@@ -0,0 +1,45 @@
+import { Request, Response, NextFunction } from 'express'
+
+import config, { privateApiVersions } from '../config'
+import { ParseError, ParseErrorType } from '../utils/errors'
+
+export default function checkPublicApiVersionHeaders(
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): void {
+  // Add our Server-Version headers to all successful responses.
+  // This should be the most recent version of the PayID protocol / PayID private API this server knows how to handle.
+  // We add it early so even errors will respond with Server-Version headers.
+  res.header('PayID-Server-Version', config.app.payIdVersion)
+  res.header('PayID-API-Server-Version', config.app.privateApiVersion)
+
+  const payIdApiVersionHeader = req.header('PayID-API-Version')
+
+  // Checks if the PayID-API-Version header exists
+  if (!payIdApiVersionHeader) {
+    throw new ParseError(
+      "A PayID-API-Version header is required in the request, of the form 'PayID-API-Version: YYYY-MM-DD'.",
+      ParseErrorType.MissingPayIdApiVersionHeader,
+    )
+  }
+
+  const dateRegex = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/u
+  const regexResult = dateRegex.exec(payIdApiVersionHeader)
+  if (!regexResult) {
+    throw new ParseError(
+      "A PayID-API-Version header must be in the form 'PayID-API-Version: YYYY-MM-DD'.",
+      ParseErrorType.InvalidPayIdApiVersionHeader,
+    )
+  }
+
+  // Because they are ISO8601 date strings, we can just do a string comparison
+  if (payIdApiVersionHeader < privateApiVersions[0]) {
+    throw new ParseError(
+      `The PayID-API-Version ${payIdApiVersionHeader} is not supported, please try upgrading your request to at least 'PayID-API-Version: ${privateApiVersions[0]}'`,
+      ParseErrorType.UnsupportedPayIdApiVersionHeader,
+    )
+  }
+
+  next()
+}

src/middlewares/sendSuccess.ts

@@ -9,9 +9,9 @@ export default function sendSuccess(req: Request, res: Response): void {
   if (status === HttpStatus.Created) {
     // The first part of the destructured array will be "", because the string starts with "/"
     // And for PUT commands, the path could potentially hold more after `userPath`.
-    const [, version, userPath] = req.originalUrl.split('/')
+    const [, userPath] = req.originalUrl.split('/')
 
-    const locationHeader = ['', version, userPath, res.locals.payId].join('/')
+    const locationHeader = ['', userPath, res.locals.payId].join('/')
 
     res.location(locationHeader)
   }

src/middlewares/users.ts

@@ -24,7 +24,7 @@ export async function getUser(
   if (!payId) {
     return handleHttpError(
       HttpStatus.BadRequest,
-      'A `payId` must be provided in the path. A well-formed API call would look like `GET /v1/users/alice$xpring.money`.',
+      'A `payId` must be provided in the path. A well-formed API call would look like `GET /users/alice$xpring.money`.',
       res,
     )
   }
@@ -106,7 +106,7 @@ export async function putUser(
   if (!payId) {
     return handleHttpError(
       HttpStatus.BadRequest,
-      'A `payId` must be provided in the path. A well-formed API call would look like `PUT /v1/users/alice$xpring.money`.',
+      'A `payId` must be provided in the path. A well-formed API call would look like `PUT /users/alice$xpring.money`.',
       res,
     )
   }
@@ -178,7 +178,7 @@ export async function deleteUser(
   if (!payId) {
     return handleHttpError(
       HttpStatus.BadRequest,
-      'A PayID must be provided in the path. A well-formed API call would look like `GET /v1/users/alice$xpring.money`.',
+      'A PayID must be provided in the path. A well-formed API call would look like `GET /users/alice$xpring.money`.',
       res,
     )
   }

src/routes/privateAPIRouter.ts

@@ -1,5 +1,6 @@
 import * as express from 'express'
 
+import checkPrivateApiVersionHeaders from '../middlewares/checkPrivateApiVersionHeaders'
 import errorHandler, { wrapAsync } from '../middlewares/errorHandler'
 import sendSuccess from '../middlewares/sendSuccess'
 import { getUser, postUser, putUser, deleteUser } from '../middlewares/users'
@@ -10,10 +11,27 @@ const privateAPIRouter = express.Router()
  * Routes for the private API so that authorized parties can post PayID mappings to the PayID database.
  */
 privateAPIRouter
-  .get('/*', wrapAsync(getUser), sendSuccess)
-  .post('/', express.json(), wrapAsync(postUser), sendSuccess)
-  .put('/*', express.json(), wrapAsync(putUser), sendSuccess)
-  .delete('/*', wrapAsync(deleteUser), sendSuccess)
+  .get('/*', checkPrivateApiVersionHeaders, wrapAsync(getUser), sendSuccess)
+  .post(
+    '/',
+    express.json(),
+    checkPrivateApiVersionHeaders,
+    wrapAsync(postUser),
+    sendSuccess,
+  )
+  .put(
+    '/*',
+    express.json(),
+    checkPrivateApiVersionHeaders,
+    wrapAsync(putUser),
+    sendSuccess,
+  )
+  .delete(
+    '/*',
+    checkPrivateApiVersionHeaders,
+    wrapAsync(deleteUser),
+    sendSuccess,
+  )
 
   // Error handling middleware needs to be defined last
   .use(errorHandler)