Tutorial #2: Save and Restore Records

All the Access Record routes are aliased with a shorthand, so /api/ar/c/ may also be accessed at /c/.

1) Create a New Record

In order to create a new record, POST to /api/ar/c/ with any body content. The Content-Type header on the POST request will automatically be associated to the record and will be returned with it when restored.

There are two optional query parameters for creating and updating records: ar and arv.

• The ar query parameter is an HK1 reference to an Access Record which will then associate that Access Record to the new record being created.
• The arv query parameter may only take on the value of "1", which will simply validate authorization to the Access Record and provide fallback content.

const node = 'iv-cos'
const port = 443
const api_root = `https://${ node }.encipher.sk:${ port }`

let formData = new FormData()
formData.append( 'content', 'big ol blob of data' )

fetch(
  `${ api_root }/api/ar/c/`
  , {
      method: 'POST' // or use PUT when updating existing records
    , body: formData
  }
)
.then( response => response.json() )
.then( data => console.log( data ) )

curl \
-H "Content-Type: application/json" \
-d '{"id": 1234, "content": "some interesting information"}' \
-X POST https://iv-cos.encipher.sk:443/api/ar/c/

/api/ar/c/ will return the following:

• Two headers x-hk1 and x-hk2 with hexadecimal-encoded HK1 reference and HK2 location tokens for the record.
• A JSON object with the property hk21_json with an array of the HK2 location first and HK1 reference second.

{
  "hk21": [
    "dd26f9d8b953efa0a567fcd341502ff62c0682d69e66fcfb7a2c44c538db4428",
    "12dadd17562a8da5b2ee552dac328553f90f400594a69b840555e5e5f11869a6"
  ]
}

The hk21 JSON array is simply the HK2 location followed by the HK1 reference in order.

2) Restore a Record

Use an HTTP GET request with the record's HK1 reference in order to retrieve the record:

const node = 'iv-cos'
const port = 443
const api_root = `https://${ node }.encipher.sk:${ port }`
const hk1 = '12dadd17562a8da5b2ee552dac328553f90f400594a69b840555e5e5f11869a6'

fetch( `${ api_root }/api/ar/c/${ hk1 }` )
.then( response => { response.blob().then( blob => {
    console.log( 'Content-Type:', response.headers.get( 'Content-Type' ) )
    console.log( 'Raw data:', blob )
  })
})

curl https://iv-cos.encipher.sk:443/api/ar/c/12dadd17562a8da5b2ee552dac328553f90f400594a69b840555e5e5f11869a6

A successful response will be the raw data for the stored record as well as a header with the Content-Type supplied when it was first stored.

3) Update an Existing Record

Simply follow the directions in step #1 except change the HTTP method to PUT instead of POST in order to patch an existing record. An hk21 key (and corresponding x-hk1 and x-hk2 headers) will be returned if successful. The HK1 reference and HK2 location will be the same when updating an existing record.

Next steps:

• Go back home.
• Go back to Tutorial #1 to learn how to authenticate!
• Go to Tutorial #3 to learn how to manage records using Access Records!