From 890ac24cda901c25ce3e868a20ca9030efb8b60f Mon Sep 17 00:00:00 2001 From: Rebecca Millichamp Date: Mon, 4 Mar 2019 11:10:11 +0100 Subject: [PATCH 01/15] updated intro until events in reference docs --- source/includes/_addresses.md | 13 +++-- source/includes/_coupons.md | 12 ++-- source/includes/_credits.md | 25 ++++---- source/includes/_events.md | 6 +- source/includes/_intro.md | 106 ++++++++++++++++++---------------- 5 files changed, 85 insertions(+), 77 deletions(-) diff --git a/source/includes/_addresses.md b/source/includes/_addresses.md index a32337884fe..8495c913eed 100644 --- a/source/includes/_addresses.md +++ b/source/includes/_addresses.md @@ -15,16 +15,17 @@ country | `string` | The country of Address geo | `array` | The geo position of Address raw | `object` | All information like address, country, zip code, etc... from service alias | `string` | The alias of Address +organization_name | `string` | The name of the organization at the given address if applicable service | `string` | The service used for Address _default google_ -### service +### Services Possibilities | ------------- | -google | -pca | +Google | +PCA | -## Retrieves an Address +## Retrieving an Address > Definition @@ -155,6 +156,6 @@ Host: api.kvass.ai Arguments | Type | Description --------- | ---- | ------ -service | `string` | Chose the service you want use -type | `string` | Define the type of your search, if it's street name, zip code, etc +service | `string` | Chose the service you want to use +type | `string` | Define your search parameter, if it's street name, zip code, etc **query** | `string` | Query is what you want to search for e.g.: "Tordenskioldsgate 3, Oslo" diff --git a/source/includes/_coupons.md b/source/includes/_coupons.md index 433920e05d7..d05c1a52424 100644 --- a/source/includes/_coupons.md +++ b/source/includes/_coupons.md @@ -1,6 +1,6 @@ # Coupons -Coupons are a great way to offer discounts or vouchers to your Customers. They can be used together with multiple business models: Orders, Invoices and Subscriptions. +Coupons are a great way to offer discounts or vouchers to your customers. They can be used together with multiple business models: Orders, Invoices and Subscriptions. ## Coupon Object @@ -8,17 +8,17 @@ Coupons are a great way to offer discounts or vouchers to your Customers. They c Attributes | Types | Description ---------- | ----- | ----------- **name** | `string` | Name of the coupon -**code** | `string` | The code to be used by a costumer. By default, the code is automatically generated (a string of 6 characters long, e.g: Nz42kL), but you can also create our own. +**code** | `string` | The code to be used by a customer. By default, the code is automatically generated (a string of 6 characters long, e.g: Nz42kL), but you can also create our own. percent_off | `number` | The discount percentage, should be between `0.` and `1.`, for example: 0.2 means 20% of the total amount. amount_off | `number` | Discount amount, for example: 100.50, means that the next payment will be decreased by 100.50. currency | `string` | ISO 4217 code of currency, for example: "EUR" -starting_date | `object` | Define when can the coupon start being used. By default, it'll start at the time of creation, but it could be defined for the future. If defined in the future, it means the coupon could not be used before the `starting_date`, `timestamp` format. _Default `now`_ -ending_date | `object` | The date when the coupon will stop being available. `timestamp` format. +starting_date | `object` | Define when the coupon can start being used. By default, it'll start at the time of creation, but it could be defined for the future. If defined in the future, it means the coupon cannot be used before the `starting_date`. `timestamp` format. _Default `now`_ +ending_date | `object` | The expiry date of the coupon. `timestamp` format. max_redemptions | `integer` | The number of times a coupon can be used. When the `used_count` is equal to the `max_redemption` then the coupon becomes unusable. used_count | `integer` | Automatically incremented by each use. -As you can see, there are two type of discount: percent_off and amount_off. +As you can see, there are two types of discounts: percent_off and amount_off. It's important to remember: a coupon can only have one of them at the same time. But if you want to change the type of discount you can do it easily with a `PUT coupons/` (There is an example [here](#switch-the-discount-type))
@@ -210,7 +210,7 @@ date_filter | `string` | Date field used for filter results. _default is `create ## Coupons Search -Retrieves a list of Coupons associate with the company. +Retrieves a list of Coupons associated with the company. > Definition diff --git a/source/includes/_credits.md b/source/includes/_credits.md index 38a01aa08a6..ee340800dc7 100644 --- a/source/includes/_credits.md +++ b/source/includes/_credits.md @@ -3,11 +3,11 @@ Attribute | Type | Description --------- | ---- | ------- uuid | `string` | The unique reference ID for the Voucher. -**initial_quantity** | `number` | The number of vouchers that will be deducted from a [User](#users). +**initial_quantity** | `number` | The number of Credits that will be deducted from a [User](#users). expires | `number` | The expiration date of the Credits. consumed | `number` | The number of Credits the user has consumed. -The `Voucher` or `Credit` is used to pay for an [`Order`](#orders) containing [`Credit Product`](#credit-product-object). +The `Voucher` or `Credit` is used to pay for an [`Order`](#orders) containing a [`Credit Product`](#credit-product-object). ## Grant Vouchers to User @@ -83,24 +83,24 @@ voucher | `number` | The new value of the `initial_amount`. ## Voucher Plan -A [`user`](#users) could also get vouchers by [`subscribing`](#subscriptions) on a `Voucher plan`. -A voucher plan has a lot of commonalities as a normal [`Plan`](#plans), but uses strictly +A [`user`](#users) can also get vouchers by [`subscribing`](#subscriptions) to a `Voucher plan`. +A voucher plan share a lot of commonalities with a normal [`Plan`](#plans), but uses only [`Credit Product`](#credit-products) in the `plan.items` instead of regular [`Products`](#products). -The [`user`](#users) will be incremented the number of vouchers corresponding to the sum of the - `plan.items.product.vouchers_required` at every billing interval. The `total_amount` in the plan, +The number of vouchers corresponding to the sum of the `plan.items.product.vouchers_required` will be charged at every billing interval for each [`user`](#users) . The `total_amount` in the plan, the amount that the user will be charged at every billing interval, will be the sum of all - `plan.items.product.price` + `plan.items.product.price`. ### Create a Voucher Plan Argument | Type | Description -------- | ---- | ------- -**plan_method** | `string` | The type of Plan, in the case a `voucher_plan`. +**method** | `string` | The type of Plan, in this case a `voucher_plan`. +**name** | `string` | The name of the Plan, in this case a `VOUCHER_PLAN`. **interval_unit** | `string` | The frequency that the Subscription acts upon.
interval_unit choices: `DAY`, `WEEK`, `MONTH`, `MONTH_END`, `ANNUAL` **billing_interval** | `string`| Defines billing frequency.
Choices: `WEEK`, `MONTH`, `MONTH_END` **currency** | `string`| Three letter ISO currency code as defined by ISO 4217.7 -**items** | `array` | An array of [`credict products`](#credit-products) and `quantity`. +**items** | `array` | An array of [`credit products`](#credit-products) and `quantity`. > Definition @@ -164,8 +164,8 @@ Content-Type: application/json ## Redeem Vouchers in an Order -The User could redeem their voucher to pay for Orders if all the [`Order.item`](#orders)'s -only contains [`Credit Products`](#credit-products) +The User can redeem their voucher to pay for Orders only if all the [`Order.items`](#orders) +are of type [`Credit Products`](#credit-products) > Definition @@ -174,7 +174,7 @@ only contains [`Credit Products`](#credit-products) POST https://api.kvass.ai/orders//redeem?expand=user.voucher ``` -> Example request: +> Example request & response: ``` http POST /orders//redeem?expand=user.voucher HTTP/1.1 @@ -183,7 +183,6 @@ Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai -{} ``` diff --git a/source/includes/_events.md b/source/includes/_events.md index 22b97b8eb49..df2fd8aa179 100644 --- a/source/includes/_events.md +++ b/source/includes/_events.md @@ -110,8 +110,8 @@ page | `number` | Which page to retrieve _default is 0_ sort | `string` | Field used to sort results _default is `-created`_ -## Receive Event by ID -Receive an event, based on its ID. +## Get Event by ID +Get an event, based on its ID. > Definition @@ -192,7 +192,7 @@ Content-Type: application/json ## Events Search -Retrieves a list of Events associated with search. +Gets a list of Events associated with search. > Definition diff --git a/source/includes/_intro.md b/source/includes/_intro.md index dd6f6049389..59b09055686 100644 --- a/source/includes/_intro.md +++ b/source/includes/_intro.md @@ -4,8 +4,6 @@ The KVASS API is a standard JSON RESTful API. The API follows the HTTP standards All responses from the API, including errors, are returned as JSON objects. -The API is separated into 2 different environments: - The **Endpoint** of the API is: `api.kvass.ai` ## Authentication @@ -13,20 +11,23 @@ The **Endpoint** of the API is: `api.kvass.ai` ``` http GET / HTTP/1.1 Content-Type: application/json +Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai ``` -> Make sure to replace `` with your API key. +> Make sure to replace `` with your personal bearer token and `` with your API key. + +KVASS uses these two identifiers to allow access to the API. If you want access to our APIs, please get in touch through our [website](https://www.kvass.ai/). -KVASS uses API keys to allow access to the API. If you want access to our APIs, please get in touch through our [website](https://www.kvass.ai/). +All API requests should include both identifiers in the headers: -All API requests should include this key in the headers*: +Authorization: Bearer ``
+X-Kvass-Api-Key: `` -`X-Kvass-Api-Key: ` ## Errors @@ -40,7 +41,7 @@ Error Code | Reason | Description ---------- | ------- | ------- 400 | Bad Request | Your request is malformed or missing mandatory data. 401 | Unauthorized | Your API key is either wrong, missing or you have no permissions for this request. -403 | Forbidden | Your request is trying to access data it has no credentials for +403 | Forbidden | Your request is trying to access data without the required credentials 404 | Not Found | The specified resource could not be found. 409 | Conflict | There was a conflict with processing your request. Try later or change the data being submitted 415 | Unsupported Media Type | The requests' payload is in a format that is not supported by this method on the target resource. @@ -52,8 +53,9 @@ Error Code | Reason | Description > Example request: ```http -GET /payment_methods//?expand=user HTTP/1.1 +GET /payment_methods/?expand=user HTTP/1.1 Content-Type: application/json +Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai ``` @@ -73,7 +75,7 @@ Content-Type: application/json } ``` -Many response objects will contain IDs for related objects in the response. For example, an Order might have a User ID associated. If you want to expand the actual user information, you can use the `expand` query parameter. +Many response objects will contain IDs for related objects in the response. For example, an Order might have an associated User ID. If you want to expand the actual user information, you can use the `expand` query parameter. You can also nest expand requests with the dot property. For example, requesting payments.payment_method on an order will expand the payments property into a list of Payment objects, and will then expand the payment method property into a full Payment Method object. @@ -82,7 +84,7 @@ in the URL query string param expand that defines which fields that you want to For example: -`GET /orders//?expand=user,provider,items.product` +`GET /orders/?expand=user,provider,items.product` ## Common Object fields @@ -105,17 +107,16 @@ user | User associated with the object ``` http GET /orders?size=10&page=1 HTTP/1.1 Content-Type: application/json +Authorization: Bearer X-Kvass-Api-Key: Host: api.kvass.ai ``` -> Example request using only `size`: +> Example response headers: ``` http GET /orders?size=100 HTTP/1.1 Content-Type: application/json -X-Kvass-Api-Key: -Host: api.kvass.ai X-Pagination-Total: 212 ``` @@ -129,23 +130,23 @@ The return of a response header contains the total count: `X-Pagination-Total: 2 ## Retrieve items The models ([Users](#users), [Invoices](#invoices), [Issuers](#issuers), etc.) -describe below can be retrieved by two different ways, *searching* or a usual GET API call. +described below can be retrieved in two different ways, *searching* or a usual GET API call. -In both ways, you can use pagination, sorting, and filter the results by date to navigate big lists. -Additionally, the search method is using the argument `query`. -Each model that has the ability to do a search will be explained more thoroughly their respective chapters, +In both ways, you can use pagination, sorting, and filtering of the results by date to navigate big lists. +Additionally, the search method uses the argument `query`. +Each model that has the ability to do a search will be explained more thoroughly in their respective chapters, but all the models have a search by `ID` in common. > Definition GET ``` -GET https://api.kvass.ai/model +GET https://api.kvass.ai/ ``` > Example GET request: ``` http -GET /model HTTP/1.1 +GET / HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: @@ -169,13 +170,13 @@ Content-Type: application/json > Definition SEARCH ``` -GET https://api.kvass.ai/model/search +GET https://api.kvass.ai//search ``` > Example SEARCH request: ``` http -GET /model/search?query=a0b1c2d3e4d5c6b7a8b94242 HTTP/1.1 +GET //search?query=a0b1c2d3e4d5c6b7a8b94242 HTTP/1.1 Content-Type: application/json Authorization: Bearer X-Kvass-Api-Key: @@ -206,14 +207,27 @@ sort | `string` | Model specific attributes for sorting results ### Getting list of models -The `Get` method allows you to retrieve all items from a model in a list. -Some models give you additional arguments for filter the requests (e.g: status filter). +The `Get` method allows you to retrieve a list of all items of a certain model type. +Some models give you additional arguments for filtering the requests (e.g: status filter). + +The available models are: + ++ Coupons ++ Events ++ Invoices ++ Issuers ++ Metrics ++ Orders ++ Plans ++ Payments ++ Payment Methods ++ Products ++ Providers ++ Resources ++ Subscriptions ++ Users ++ Webhooks - | Invoices | Issuers | Orders | Payments | Products | Providers | Users | Resources -------- | -------- | ------- | ------ | -------- | -------- | --------- | ----- | ----- -*Filter by date* | x | x | x | x | x | x | x | x -*Pagination* | x | x | x | x | x | x | x | x -*Sorting* | x | x | x | x | x | x | x | x ### Search on model @@ -223,12 +237,6 @@ This method allows you to retrieve a list of items matching with a search query, like `user_name` or `account_number`, without specifying that you are searching for `user_name` or `account_number`. - | Invoices | Issuers | Orders | Payments | Products | Providers | Users | Resources -------- | -------- | ------- | ------ | -------- | -------- | --------- | ----- | ----- -*Filter by date* | x | x | x | x | x | x | x | x -*Pagination* | x | x | x | x | x | x | x | x -*Sorting* | x | x | x | x | x | x | x | x - ### Search model by tags @@ -239,15 +247,15 @@ There are 3 ways of getting models by tags: 1. Get all models that contain a specific tag. -*Code: `?tags=tag_1`* + *Code: `?tags=tag_1`* 2. Get models that match multiple tags by separating the different tags in the query by `+`. -*Code: `?tags=tag_1+tag_2`* + *Code: `?tags=tag_1+tag_2`* 3. Get models that contain only 1 specific tag. -*Code: `?tags=tag_1+`* + *Code: `?tags=tag_1+`* ###Tag Query Examples @@ -265,15 +273,15 @@ If you only want models that match both `tag1_` and `tag_2`, separate the tags b - `GET some-route?tags=tag_1,tag_2` -Here we have two expressions: `tag_1` and `tag_2`, which would you returns all models contain `tag_1` or `tag_2` +Here we have two expressions: `tag_1` and `tag_2`, which would return all models containing `tag_1` or `tag_2` -- `GET some-route?tags=tag_2+tag_3,tag_1,tag_4+tag_5+tag_3` +- `GET some-route?tags=tag_1+tag_2,tag_3,tag_4+tag_5` -Here we have three expressions: `tag_2+tag_3`, `tag_1` and, `tag_4+tag_5`, which would you returns all models contain `tag_1` and `tag_2`, models contain `tag_1` and, models contain `tag_4`, `tag_5` and, `tag_3`. +Here we have three expressions: `tag_1+tag_2`, `tag_3` and, `tag_4+tag_5`, which would return all models containing both `tag_1` and `tag_2`, models containing `tag_3` and, models containing both `tag_4` and `tag_5`. -- `Get some-route?tags=tag_2+` +- `Get some-route?tags=tag_1+` -In the query above, the query is 'tag_2+'. This query will return models that match the tag 'tag_2' +In the query above, the query is 'tag_1+'. This query will return models that match the tag 'tag_1'