Skip to content

Commit ccff7d5

Browse files
duncanmccleanduncanmcclean
committed
JSON API doc tweaks
1 parent 7be27ce commit ccff7d5

File tree

1 file changed

+110
-78
lines changed

1 file changed

+110
-78
lines changed

‎docs/frontend/json-api/endpoints.md‎

Lines changed: 110 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,22 @@
22
title: "JSON API: Endpoints"
33
---
44

5-
## Cart
5+
## Current Cart
6+
Returns the customer's cart.
67

7-
[//]: # (todo: order keys alphabetically))
8+
@blade
9+
<x-api-endpoint method="GET" path="/!/cargo/cart" />
10+
@endblade
11+
12+
## Update the cart
13+
Updates the customer's cart. You can post customer information, redeem a discount code, or pass any other order fields here.
814

15+
[//]: # (Note: Parameters are duplicated in frontend/tags/cart.md)
916
@blade
10-
@include('markdown.api-endpoint', [
11-
'method' => 'GET',
12-
'path' => '/!/cargo/cart',
13-
'description' => "Returns the customer's cart.",
14-
])
15-
16-
@include('markdown.api-endpoint', [
17-
'method' => 'POST',
18-
'path' => '/!/cargo/cart',
19-
'description' => "Updates the customer's cart. You can post customer information, redeem a discount code, or pass any other order fields here.",
20-
'parameters' => [
17+
<x-api-endpoint
18+
method="POST"
19+
path="/!/cargo/cart"
20+
:parameters="[
2121
[
2222
'key' => 'customer',
2323
'type' => 'array',
@@ -47,20 +47,26 @@ title: "JSON API: Endpoints"
4747
['key' => 'billing_country', 'type' => 'string', 'description' => 'Must be in [ISO3](https://www.iso.org/obp/ui#iso:pub:PUB500001:en) format.'],
4848
['key' => 'billing_state', 'type' => 'string', 'description' => 'Must match one of the states in [Cargo\'s `states.json` file](https://github.com/duncanmcclean/statamic-cargo/blob/main/resources/json/states.json).'],
4949
['key' => '*', 'description' => 'Any other fields defined in your [order blueprint](/docs/orders#blueprint).'],
50-
],
51-
])
52-
53-
@include('markdown.api-endpoint', [
54-
'method' => 'DELETE',
55-
'path' => '/!/cargo/cart',
56-
'description' => "Deletes the customer's cart.",
57-
])
58-
59-
@include('markdown.api-endpoint', [
60-
'method' => 'POST',
61-
'path' => '/!/cargo/cart/line-items',
62-
'description' => "Adds a line item to the customer's cart.",
63-
'parameters' => [
50+
]"
51+
/>
52+
@endblade
53+
54+
## Delete the cart
55+
Deletes the customer's cart.
56+
57+
@blade
58+
<x-api-endpoint method="DELETE" path="/!/cargo/cart" />
59+
@endblade
60+
61+
## Add a line item
62+
Adds a line item to the customer's cart.
63+
64+
[//]: # (Note: Parameters are duplicated in frontend/tags/cart.md)
65+
@blade
66+
<x-api-endpoint
67+
method="POST"
68+
path="/!/cargo/cart/line-items"
69+
:parameters="[
6470
['key' => 'product', 'type' => 'string', 'required' => true],
6571
['key' => 'variant', 'type' => 'string', 'description' => 'Required when adding a variant product.'],
6672
['key' => 'quantity', 'type' => 'integer', 'description' => 'Defaults to `1`'],
@@ -78,14 +84,19 @@ title: "JSON API: Endpoints"
7884
],
7985
],
8086
['key' => '*', 'description' => 'Any other data you\'d like to persist on the line item.'],
81-
],
82-
])
83-
84-
@include('markdown.api-endpoint', [
85-
'method' => 'PATCH',
86-
'path' => '/!/cargo/cart/line-items/{lineItem}',
87-
'description' => "Updates a line item on the customer's cart. The `{lineItem}` should be the ID of the line item you wish to update.",
88-
'parameters' => [
87+
]"
88+
/>
89+
@endblade
90+
91+
## Update a line item
92+
Updates a line item on the customer's cart. The `{lineItem}` should be the ID of the line item you wish to update.
93+
94+
[//]: # (Note: Parameters are duplicated in frontend/tags/cart.md)
95+
@blade
96+
<x-api-endpoint
97+
method="PATCH"
98+
path="/!/cargo/cart/line-items/{lineItem}"
99+
:parameters="[
89100
['key' => 'variant', 'type' => 'string', 'description' => 'Required when the product is a variant product.'],
90101
['key' => 'quantity', 'type' => 'integer'],
91102
[
@@ -102,59 +113,80 @@ title: "JSON API: Endpoints"
102113
],
103114
],
104115
['key' => '*', 'description' => 'Any other data you\'d like to persist on the line item.'],
105-
],
106-
])
107-
108-
@include('markdown.api-endpoint', [
109-
'method' => 'DELETE',
110-
'path' => '/!/cargo/cart/line-items/{lineItem}',
111-
'description' => "Removes a line item from the customer's cart. The `{lineItem}` should be the ID of the line item you wish to remove.",
112-
])
113-
114-
@include('markdown.api-endpoint', [
115-
'method' => 'GET',
116-
'path' => '/!/cargo/cart/shipping',
117-
'description' => "Returns the available shipping options for the customer's cart. <br><br> When there's no address on the cart, this endpoint will return a 422 status code. When the customer doesn't have a cart, this endpoint will return a 404 status code.",
118-
])
119-
120-
@include('markdown.api-endpoint', [
121-
'method' => 'GET',
122-
'path' => '/!/cargo/cart/payment-gateways',
123-
'description' => "Returns the available payment gateways for the customer's cart, including the array returned by the payment gateway's `setup` method. <br><br> Payment Gateways will be returned *even* when the cart total is £0. In this case, no `setup` data will be returned. <br><br> When the customer doesn't have a cart, this endpoint will return a 404 status code.",
124-
])
116+
]"
117+
/>
125118
@endblade
126119

127-
## Checkout
120+
## Remove a line item
121+
Removes a line item from the customer's cart. The `{lineItem}` should be the ID of the line item you wish to remove.
128122

129123
@blade
130-
@include('markdown.api-endpoint', [
131-
'method' => 'GET & POST',
132-
'path' => '/!/cargo/cart/checkout',
133-
'description' => "When the cart total is equals to £0, you may use this endpoint to create an order without payment. <br><br> When successful, this endpoint will return a redirect response to the checkout confirmation page. <br><br> When the order requires payment, this endpoint will return a 404 status code.",
134-
'parameters' => [
124+
<x-api-endpoint method="DELETE" path="/!/cargo/cart/line-items/{lineItem}" />
125+
@endblade
126+
127+
## Available Shipping Methods
128+
Returns the available shipping options for the customer's cart.
129+
130+
This endpoint will return a `422` status code when no shipping address is set on the cart.
131+
132+
@blade
133+
<x-api-endpoint method="GET" path="/!/cargo/cart/shipping" />
134+
@endblade
135+
136+
## Available Payment Gateways
137+
Returns the available payment gateways for the customer's cart, including the array returned by the payment gateway's `setup` method.
138+
139+
:::tip note
140+
Payment Gateways will be returned *even* when the cart total is £0. In this case, no `setup` data will be returned.
141+
:::
142+
143+
@blade
144+
<x-api-endpoint method="GET" path="/!/cargo/cart/payment-gateways" />
145+
@endblade
146+
147+
## Checkout: £0 order
148+
When the cart total is equals to £0, you may use this endpoint to create an order without payment.
149+
150+
When successful, this endpoint will return a redirect response to the checkout confirmation page.
151+
152+
When the order requires payment, this endpoint will report a `404` status code.
153+
154+
@blade
155+
<x-api-endpoint
156+
method="GET / POST"
157+
path="/!/cargo/cart/checkout"
158+
:parameters="[
135159
['key' => 'discount_code', 'type' => 'string'],
136-
],
137-
])
138-
139-
@include('markdown.api-endpoint', [
140-
'method' => 'GET & POST',
141-
'path' => '/!/cargo/payments/{gateway}/checkout',
142-
'description' => "When the order requires payment, you may use this endpoint to create the order. The `{gateway}` should be the handle of the payment gateway you wish to check out using. <br><br> When successful, this endpoint will return a redirect response to the checkout confirmation page. <br><br> When the order does not require payment, this endpoint will return a 404 status code.",
143-
'parameters' => [
160+
]"
161+
/>
162+
@endblade
163+
164+
## Checkout: Paid Order
165+
When the order requires payment, you may use this endpoint to create the order. The `{gateway}` should be the handle of the payment gateway you wish to check out using.
166+
167+
When successful, this endpoint will return a redirect response to the checkout confirmation page.
168+
169+
When the order does not require payment, this endpoint will return a `404` status code.
170+
171+
@blade
172+
<x-api-endpoint
173+
method="GET / POST"
174+
path="/!/cargo/cart/payments/{gateway}/checkout"
175+
:parameters="[
144176
['key' => 'discount_code', 'type' => 'string'],
145-
],
146-
])
177+
]"
178+
/>
147179
@endblade
148180

149181
## States
182+
Returns an array of states for a given country.
150183

151184
@blade
152-
@include('markdown.api-endpoint', [
153-
'method' => 'GET',
154-
'path' => '/!/cargo/states',
155-
'description' => "Returns an array of states for a given country.",
156-
'parameters' => [
185+
<x-api-endpoint
186+
method="GET"
187+
path="/!/cargo/states"
188+
:parameters="[
157189
['key' => 'country', 'type' => 'string', 'required' => true, 'description' => 'Must be in [ISO3](https://www.iso.org/obp/ui#iso:pub:PUB500001:en) format.'],
158-
],
159-
])
190+
]"
191+
/>
160192
@endblade

0 commit comments

Comments
 (0)