asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: adds first version of REST docs (#116)

Browse Source
This commit is contained in:
Sebastian Rindom
2020-09-30 21:17:22 +02:00
committed by GitHub
parent 1da1ebbb5e
commit 47e2ad2952
29 changed files with 14653 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/api/store/carts.md
View File

@@ -1,9 +0,0 @@
POST /carts
GET /carts/:id
POST /carts/:id
POST /carts/:id/line-items
POST /carts/:id/line-items/:line_id
GET /carts/:id/shipping-options
POST /carts/:id/payment-sessions

317
docs/api/store/endpoints/carts.yaml Normal file
View File

@@ -0,0 +1,317 @@
title: Carts
domain: store
route: /carts
description: >
A Cart is the preliminary step to an Order. The Cart holds a collection of
items that the customer wishes to purchase, along with the customer's
preferred payment and shipping method.
endpoints:
- path: /
method: POST
title: Create a Cart
body:
- name: region_id
type: String
required: false
description: Id of the region to associate the cart with.
- name: items
type: List
required: false
description: List of objects with `variantId` and `quantity`.
description: >
Creates a Cart within the given region and with the initial items. If no
`region_id` is provided the cart will be associated with the first Region
available. If no items are provided the cart will be empty after creation.
If a user is logged in the cart's customer id and email will be set.
- path: /:id
method: GET
title: Retrieve a Cart
params:
- name: id
type: String
description: Id of the cart.
description: >
Retrieves an existing cart.
- path: /:id
method: POST
title: Update a Cart
params:
- name: id
type: String
description: Id of the cart.
body:
- name: region_id
type: String
description: Id of a region.
- name: email
type: String
description: >
Customer's email where they will receive transactional emails etc.
- name: billing_address
type: Address
description: >
The billing address for the order.
- name: shipping_address
type: Address
description: >
The shipping address for the order. Will be sent to the fulfillment
provider when the items are ready to be shipped.
- name: discounts
type: List
description: >
A list of objects with `code` that represents a discount code to be
applied to the cart.
description: >
Updates an existing cart with the provided data. Updating the `region_id`
will change the prices of the items in the cart to match the prices
defined for the region. You can apply multiple discounts at once by
calling the endpoint with an array of discounts.
- path: /:id/line-items
method: POST
title: Add a Line Item to a Cart
params:
- name: id
type: String
body:
- name: variant_id
type: String
required: true
description: The id of the variant that should be added to the cart.
- name: quantity
type: Integer
required: true
description: >
The quantity of the variant to add to the cart. Must be
greater than 0.
- name: metadata
type: Object
description: >
Optional metadata that may be needed for display purposes or other
functionality.
- path: /:id/line-items/:line_id
method: POST
title: Update a Line Item
params:
- name: id
type: String
description: Id of the cart to update.
- name: line_id
type: String
description: Id of the line to update.
body:
- name: quantity
type: Integer
description: The desired quantity of the line item.
description: >
Updates the quantity of a line item. If the variant associated with the
line item is stock managed, the endpoint will respond with an error when
the inventory level cannot fulfill the desired quantity.
- path: /:id/line-items/:line_id
method: DELETE
title: Remove a Line Item
params:
- name: id
type: String
description: Id of the cart.
- name: line_id
type: String
description: Id of the line item to remove.
description: >
Removes a the given line item from the cart.
- path: /:id/discounts/:code
method: DELETE
title: Remove a Discount Code
params:
- name: id
type: String
description: Id of the cart.
- name: code
type: String
description: The discount code to remove
description: Removes a discount code from the cart.
- path: /:id/payment-sessions
method: POST
title: Initialize Payment Sessions for a Cart
params:
- name: id
type: String
description: Id of the cart.
description: >
Initializes the payment sessions that can be used to pay for the items of
the cart. This is usually called when a customer proceeds to checkout.
- path: /:id/payment-sessions/:provider_id
method: DELETE
title: Delete a Payment Session
params:
- name: id
type: String
description: Id of the cart.
- name: provider_id
type: String
description: >
Id of the provider that created the payment session to remove.
description: >
Deletes a payment session. Note that this will initialize a new payment
session with the provider. This is usually used if the payment session
reaches a state that cannot be recovered from.
- path: /:id/payment-method
method: POST
title: Set the Payment Method for a Cart
params:
- name: id
type: String
description: Id of the cart.
body:
- name: provider_id
type: String
required: true
description: >
Id of the provider that offers the payment method.
- name: data
type: Dictionary
description: >
Used to hold any data that the payment method may need to process the
payment. The requirements of `data` will be different across payment
methods, and you should look at your installed payment providers to
find out what to send.
description: >
Adds or updates the payment method that will be used to pay for the items
in the cart. The payment is not processed until the payment provider's
authorization functionality is called. You should consult with your
installed payment plugins to find information about how to authorize a
payment.
- path: /:id/shipping-methods
method: POST
title: Add a Shipping Method to a Cart
params:
- name: id
type: String
description: Id of the cart.
body:
- name: option_id
type: String
required: true
description: The id of the shipping option to use.
- name: data
type: Dictionary
description: >
Used to hold any data that the shipping method may need to process the
fulfillment of the order. Look at the documentation for your installed
fulfillment providers to find out what to send.
description: >
Adds a shipping method to the cart.
response: |
{
"cart": {
"_id": "5f68a234d694d000217a4d64",
"customer_id": "",
"region_id": "5f4cd57a5d1e3200214c0e4e",
"email": "",
"shipping_address": {
"_id": "5f68a234d694d000217a4d65",
"country_code": "US"
},
"items": [
{
"is_giftcard": false,
"has_shipping": false,
"returned": false,
"fulfilled": false,
"fulfilled_quantity": 0,
"returned_quantity": 0,
"_id": "5f72f79c2834b400216b1a54",
"title": "Line Item",
"description": "240x260",
"quantity": 1,
"thumbnail": "https://example-thumbnail.com",
"content": {
"unit_price": 303.2,
"variant": {
"_id": "5f4cf81a2ac41700211f6e63",
"barcode": "",
"image": "",
"published": true,
"inventory_quantity": 11,
"allow_backorder": false,
"manage_inventory": true,
"title": "1234",
"sku": "SKU1234",
"ean": "1111111111111",
"options": [
{
"_id": "5f4cf81a2ac41700211f6e64",
"value": "1234",
"option_id": "5f4cf81a2ac41700211f6e62"
}
],
"prices": [
{
"_id": "5f4cf81a2ac41700211f6e65",
"currency_code": "SEK",
"amount": 3180
},
{
"_id": "5f4cf81a2ac41700211f6e66",
"currency_code": "EUR",
"amount": 303.2
},
{
"_id": "5f4cf81a2ac41700211f6e67",
"currency_code": "DKK",
"amount": 2260
}
],
"metadata": {
"origin_country": "Portugal"
}
},
"product": {
"_id": "5f4cf81a2ac41700211f6e61",
"description": "100% Organic",
"tags": "",
"is_giftcard": false,
"images": [],
"thumbnail": "https://example-thumbnail.com",
"variants": [
"5f4cf81a2ac41700211f6e63"
],
"published": false,
"title": "Line Item",
"options": [
{
"values": [],
"_id": "5f4cf81a2ac41700211f6e62",
"title": "Size"
}
]
},
"quantity": 1
}
}
],
"discounts": [],
"payment_sessions": [],
"shipping_methods": [],
"shipping_total": 0,
"discount_total": 0,
"tax_total": 0,
"subtotal": 303.2,
"total": 303.2,
"region": {
"_id": "5f4cd57a5d1e3200214c0e4e",
"tax_rate": 0,
"countries": [
"US"
],
"payment_providers": [
"stripe"
],
"fulfillment_providers": [
"shiphero"
],
"name": "United States",
"currency_code": "EUR",
"tax_code": "ABR"
}
}
}

166
docs/api/store/endpoints/customers.yaml Normal file
View File

@@ -0,0 +1,166 @@
title: Customers
domain: store
route: /customers
description: >
Customers can create a login to view Order history and manage details.
Customers must have unique emails.
endpoints:
- path: /
method: POST
title: Create a Customer Login
body:
- name: email
type: String
required: true
description: The Customer's email; must be unique.
- name: first_name
type: String
required: true
description: The Customer's first name.
- name: last_name
type: String
required: true
description: The Customer's last name.
- name: password
type: String
required: true
description: The Customer's desired password.
- name: phone
type: String
description: The customer's phone number.
description: >
Creates a customer profile with the given details. If the email has been
used on previous orders the newly created Customer profile will be able to
view the order history associated with this email.
- path: /password-reset
method: POST
title: Reset Customer password
body:
- name: email
type: String
required: true
description: The email of the Customer.
- name: token
type: String
required: true
description: >
The token that will be used to reset the password. Should be generated
with a prior call to `/password-token`.
- name: password
type: String
required: true
description: >
The new password to authenticate the user with.
description: >
Resets a customer's password. The reset call requires a valid token
- path: /password-token
method: POST
title: Request Customer password reset token
body:
- name: email
type: String
required: true
description: The email of the Customer profile to reset password for.
description: >
Generates a reset password token. The token should be sent to the customer
via an email provider. Note that this doesn't send any emails it only
generates the token and informs listeners to
`customer.password_token_generated` that the token was created.
- path: /:id
method: GET
title: Retrieve Customer
params:
- name: id
type: String
description: The id of the Customer to retrieve.
description: >
Retrieves the customer's details. The Customer identified by `id` must be
authenticated.
- path: /:id
method: POST
title: Update Customer details
params:
- name: id
type: String
description: The id of the customer.
body:
- name: first_name
type: String
description: The Customer's first name.
- name: last_name
type: String
description: The Customer's last name.
- name: password
type: String
description: >
The Customer's password. Will create a hashed value for the database.
- name: phone
type: String
description: The Customer's phone number.
description: >
Updates the customer's details. The customer identified by `id` must be
authenticated in order to call this endpoint.
- path: /:id/addresses
method: POST
title: Create a new Customer address
params:
- name: id
type: String
description: The id of the Customer.
body:
- name: address
type: Address
description: The address to add.
description: >
Adds an address to the customer's saved addresses. The customer must be
authenticated prior to making this call.
- path: /:id/addresses/:address_id
method: POST
title: Update a Customer address
params:
- name: id
type: String
description: The id of the Customer.
- name: address_id
type: String
description: The id of the saved address to update.
body:
- name: address
type: Address
description: The address to update.
description: >
Updates a saved customer address. The customer must be authenticated prior
to making this call.
- path: /:id/payment-methods
method: GET
title: Retrieve Customer's saved payment methods
params:
- name: id
type: String
description: The id of the customer.
description: >
Asks each payment provider for saved payment methods if any exist. This
will only return in methods in the case where the payment provider allows
payment methods to be saved. The customer must be authenticated in order
to call this endpoint.
response: |
{
"customer": {
"_id": "5ea80c76d9549d0006c21da7",
"email": "mrs@potato.com",
"orders": [],
"shipping_addresses": [],
"first_name": "Potato",
"last_name": "Head",
"metadata": {}
}
}

235
docs/api/store/endpoints/orders.yaml Normal file
View File

@@ -0,0 +1,235 @@
title: Orders
domain: store
route: /orders
description: >
An Order represents a selection of items purchased and holds information about
how the items have been purchased and will be fulfilled.
endpoints:
- path: /:id
method: GET
title: Retrieve an Order
params:
- name: id
type: String
description: The id of the order.
description: >
Retrieves an order.
- path: /
method: POST
title: Creates an Order
body:
- name: cartId
type: String
description: Id of the cart from which the order should be created.
description: >
Creates an order from a cart.
response: |
{
"_id": "5f65c961395b3e0021d8f994",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "awaiting",
"display_id": "1000",
"payment_method": {
"_id": "5f65c961395b3e0021d8f995",
"provider_id": "provider",
"data": {
"id": "importantForPaymentProvider",
"more": "information"
}
},
"discounts": [
{
"regions": [
"5f40ce8f7743b30021337e2b",
"5f4788eff847d30021ac331d",
"5f4cb9a07435de0021c69f09"
],
"_id": "5f626102bd79500021ea17a3",
"is_giftcard": false,
"usage_count": 6,
"disabled": false,
"code": "TEST",
"discount_rule": {
"valid_for": [],
"_id": "5f626102bd79500021ea17a4",
"description": "TEST",
"value": 99,
"type": "percentage",
"allocation": "total"
}
}
],
"shipping_methods": [
{
"name": "Always Free",
"items": [],
"_id": "5f5b7c1b55c13000213c0989",
"data": {
"id": "manual-fulfillment"
},
"profile_id": "5f3e8fd5cac0ff0021a2be66",
"price": 0,
"provider_id": "manual"
}
],
"items": [
{
"is_giftcard": false,
"has_shipping": true,
"shipped_quantity": 0,
"returned": false,
"fulfilled": false,
"fulfilled_quantity": 0,
"returned_quantity": 0,
"_id": "5f65c927395b3e0021d8f984",
"title": "Item",
"description": "70x140",
"quantity": 1,
"thumbnail": "",
"content": {
"unit_price": 316,
"variant": {
"_id": "5f40f0a2b687940021667170",
"barcode": "",
"image": "",
"published": false,
"inventory_quantity": 20,
"allow_backorder": false,
"manage_inventory": true,
"title": "1234",
"sku": "SKU1234",
"ean": "5713682002297",
"options": [
{
"_id": "5f40f0a2b687940021667171",
"value": "70x140",
"option_id": "5f40f0a2b687940021667163"
}
],
"prices": [
{
"_id": "5f40f0a2b687940021667172",
"currency_code": "EUR",
"amount": 44
},
{
"_id": "5f40f0a2b687940021667173",
"currency_code": "DKK",
"amount": 316
}
],
"__v": 0
},
"product": {
"_id": "5f40f0a2b687940021667162",
"description": "100% Good",
"tags": "",
"is_giftcard": false,
"images": [],
"thumbnail": "",
"variants": [
"5f40f0a2b687940021667164",
"5f40f0a2b687940021667168",
"5f40f0a2b68794002166716c",
"5f40f0a2b687940021667170",
"5f40f0a2b687940021667174"
],
"published": false,
"title": "Item",
"options": [
{
"values": [],
"_id": "5f40f0a2b687940021667163",
"title": "Size"
}
],
"__v": 0
},
"quantity": 1
},
"refundable": 3.95
}
],
"shipping_address": {
"_id": "5f60adf22162dd0021362beb",
"country_code": "DK",
"first_name": "John",
"last_name": "Jones",
"address_1": "Jone ST 9",
"city": "Jonstown",
"postal_code": "12332"
},
"billing_address": {
"_id": "5f60adf22162dd0021362beb",
"country_code": "DK",
"first_name": "John",
"last_name": "Jones",
"address_1": "Jone ST 9",
"city": "Jonstown",
"postal_code": "12332"
},
"region_id": "5f40ce8f7743b30021337e2b",
"email": "jojo@jon.com",
"customer_id": "5f42870e715758002170ed86",
"cart_id": "5f4bd6b47435de0021c69f04",
"tax_rate": 0.25,
"currency_code": "DKK",
"shipments": [],
"fulfillments": [],
"returns": [],
"refunds": [],
"created": "2020-09-19T09:03:29.000Z",
"shipping_total": 0,
"discount_total": 312.84,
"tax_total": 0.79,
"subtotal": 316,
"total": 3.95,
"refunded_total": 0,
"refundable_amount": 3.95,
"region": {
"_id": "5f40ce8f7743b30021337e2b",
"tax_rate": 0.25,
"countries": [
"DK"
],
"payment_providers": [
"provider"
],
"fulfillment_providers": [
"manual"
],
"name": "Denmark",
"currency_code": "DKK",
"tax_code": "D25",
"__v": 0
},
"customer": {
"_id": "5f42870e715758002170ed86",
"payment_methods": [],
"has_account": true,
"orders": [
"5f65c961395b3e0021d8f994"
],
"email": "jojo@jon.com",
"shipping_addresses": [
{
"_id": "5f60adf22162dd0021362beb",
"country_code": "DK",
"first_name": "John",
"last_name": "Jones",
"address_1": "Jone ST 9",
"city": "Jonstown",
"postal_code": "12332"
}
],
"__v": 0,
"metadata": {
"stripe_id": "cus_123123123"
},
"first_name": "John",
"last_name": "Jones",
"password_hash": "c2NyeXB0AAEAAAABAAAAAd3Q0jehDc8N3cTdqlPCfeZtF5pILidEESwxcA9Yh8PuojRYBXG0xIiFKVq1xXGfXZlY6zkp1IGBXZDHKb9ZtExImjKlFJNwFxwiiaLFS6oD"
}
}

41
docs/api/store/endpoints/regions.yaml Normal file
View File

@@ -0,0 +1,41 @@
title: Regions
domain: store
route: /regions
description: >
A Region represents a collection of countries that have common pricing
schemes, shipping options, tax schemes, etc. Carts must have a region
associated.
endpoints:
- path: /
method: GET
title: List Regions
description: >
Retrieves the regions configured for the store.
- path: /:id
method: GET
title: Retrieve a Region
params:
- name: id
type: String
description: Id of the region.
description: >
Retrieves a region
response: |
{
"region": {
"name": "Denmark",
"currency_code": "DKK",
"tax_rate": 0.25,
"countries": [
"DK"
],
"payment_providers": [
"stripe"
],
"fulfillment_providers": [
"manual"
],
"_id": "5f4cd45b5d1e3200214c0e49"
}
}