diff --git a/src/content/api/data-types.mdx b/src/content/api/data-types.mdx new file mode 100644 index 000000000..3ef7e391e --- /dev/null +++ b/src/content/api/data-types.mdx @@ -0,0 +1,74 @@ +--- +title: Data Types +description: Introduction to Data Types +draft: true +nav: + path: API + order: 4 +--- + +## Timestamp + +A point in time, usually with millisecond precision, represented as an +[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date string (eg "2021-06-11T02:51:11.000Z"). Timestamps +are in the UTC timezone as denoted by the "Z" suffix. + +## BigNumber + +A number, represented as a String, which can have arbitrary size or precision. +Most Centrapay APIs that deal with transactable value (ie. assets, payments, +etc) represent the value as BigNumbers. Depending on the context, a BigNumber +may be used to represent an integer or a decimal amount. + +## Monetary + +A monetary amount in a currency, represented as an Object. The amount is +usually an integer in the smallest denomination for the currency (ie cents) but +may be a decimal value for some currencies (eg Bitcoin). The currency is +typically represented as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. + +### Fields + +| Name | Type | Description | +| -------- | ----------------------- | ---------------------------------------------------------- | +| amount | [BigNumber](#bignumber) | Value in the currency's smallest denomination (eg. cents). | +| currency | String | Currency code (eg. "NZD"). | + +## CRN + +A Centrapay Resource Name (CRN) is a colon-delimited String that uniquely +identifies any Centrapay resource. + +The format is `crn:{account}:{type}:{id}` where "account" is the optional +Centrapay account that owns the resource, "type" is the resource type, and "id" +is the resource identifier. + +CRN is often used to refer to Users and API keys. For example: +* **User:** crn::user:e2837e88-d408-11eb-8eac-3e22fb52e878 +* **API Key:** crn:1234abc:api-key:MyAccountOwner + +## Location + +A location's represented as an Object with properties to denote the location both absolute and +by locality. + +### Required Fields + +| Name | Type | Description | +| ------- | ------ | -------------------------------------------------------------------------------------- | +| street | String | Unit, number, and name of street address. | +| city | String | City of location. | +| country | String | [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) Country code. (eg. "NZ"). | + +### Optional Fields +| Name | Type | Description | +| -------- | ------ | ------------------------------------------------------------------------------------------------------------- | +| lat | Number | Absolute latitude coordinate. If you don't provide this, we will automatically infer this from your address. | +| lng | Number | Absolute longitude coordinate. If you don't provide this, we will automatically infer this from your address. | +| suburb | String | Suburb of location. | +| postCode | String | Post or Zip code of location. | +| state | String | The state or region of the location (eg. "Auckland"). | + +## PhoneNumber + +A phone number, represented in [E.123](https://en.wikipedia.org/wiki/E.123) international notation (eg "+6421537663"). We usually use this for receiving text messages.