Your First Request

This page walks you through making your first HTTP request to the pycli API. You'll send a real request using curl, inspect the response, and understand the basic shape of the API before moving on to more advanced workflows. Getting this first call working confirms your environment is set up correctly and gives you a foundation for creating, listing, viewing, and canceling orders.

Before you begin, make sure you have the following:

• curl installed and available in your terminal (run curl --version to verify), or an alternative HTTP client such as Postman, HTTPie, or a language SDK
• Access to the pycli API base URL: https://api.example.com
• A basic understanding of JSON request and response bodies
• (Optional) jq for pretty-printing JSON responses in the terminal

The pycli API is a hosted web service — there is nothing to install to consume it. You interact with it entirely through HTTP requests.

If you want to run the API locally for development or testing, follow these steps:

1. Clone the repository and install dependencies.

   Copy

   pip install fastapi uvicorn
   

2. Start the API server.

   Copy

   uvicorn api:app --reload
   

3. Confirm the server is running. By default, uvicorn listens on http://127.0.0.1:8000. Open that URL in your browser or run:

   Copy

   curl http://127.0.0.1:8000/orders
   

   You should receive a JSON response. Replace https://api.example.com with http://127.0.0.1:8000 in all examples on this page when working locally.

The API exposes the following query parameters you can use to control the behavior of list requests. These are not global settings — you pass them per request.

For POST /orders, the request body controls the order being created. The fields are:

Omitting a required field or passing the wrong type will result in a validation error from the API.

The most common starting point is creating an order and then retrieving it. All requests go to the base URL (https://api.example.com) and expect and return JSON.

Creating an order

Send a POST request to /orders with a JSON body containing at least amount and currency:

curl -X POST https://api.example.com/orders \
  -H 'Content-Type: application/json' \
  -d '{"amount": 1500, "currency": "USD"}'

The API responds with the new order object, including its assigned id and an initial status of pending.

Fetching a single order

Once you have an order id, retrieve it by appending the id to the /orders path:

curl https://api.example.com/orders/42

Listing orders

To see multiple orders at once, call GET /orders. Use the status and limit query parameters to narrow results:

curl 'https://api.example.com/orders?status=paid&limit=10'

Canceling an order

Send a DELETE request to /orders/{order_id} to cancel an order:

curl -X DELETE https://api.example.com/orders/42

All four operations together cover the full order lifecycle supported by the API.

The examples below are self-contained and runnable. Substitute your own order_id values where shown.

Create a new order

curl -X POST https://api.example.com/orders \
  -H 'Content-Type: application/json' \
  -d '{"amount": 1500, "currency": "USD"}'

Expected response (200 OK):

{
  "id": 1,
  "amount": 1500,
  "currency": "USD",
  "status": "pending"
}

Create an order with an optional note

curl -X POST https://api.example.com/orders \
  -H 'Content-Type: application/json' \
  -d '{"amount": 500, "currency": "EUR", "note": "Rush delivery"}'

Expected response (200 OK):

{
  "id": 1,
  "amount": 500,
  "currency": "EUR",
  "status": "pending"
}

Fetch a single order by ID

curl https://api.example.com/orders/42

Expected response (200 OK):

{
  "id": 42,
  "amount": 100,
  "currency": "USD",
  "status": "paid"
}

List paid orders (up to 10 results)

curl 'https://api.example.com/orders?status=paid&limit=10'

Expected response (200 OK):

{
  "status": "paid",
  "limit": 10,
  "orders": []
}

Cancel an order

curl -X DELETE https://api.example.com/orders/42

Expected response (200 OK):

{
  "id": 42,
  "status": "canceled"
}

Use this section to diagnose the most common problems when making your first request.

Symptom: curl: (6) Could not resolve host: api.example.com

Likely cause: Your machine cannot reach the API host. This could be a network issue or an incorrect base URL.

Fix: Verify the base URL is correct and that you have an active internet connection. If running locally, replace https://api.example.com with http://127.0.0.1:8000 and confirm the server is running with uvicorn api:app --reload.

Symptom: 422 Unprocessable Entity response when calling POST /orders

Likely cause: The request body is missing a required field (amount or currency), contains a field with the wrong type (e.g. amount passed as a string instead of an integer), or the Content-Type header is missing.

Fix: Ensure your request includes -H 'Content-Type: application/json' and that the body is valid JSON with amount as an integer and currency as a string. Example of a correct body: {"amount": 1500, "currency": "USD"}.

Symptom: 404 Not Found when fetching or canceling an order

Likely cause: The order_id in the path does not correspond to an existing order, or the URL path is malformed.

Fix: Double-check the order ID you are using. Confirm the URL follows the pattern /orders/{order_id} with no extra slashes or characters.

Symptom: 400 Bad Request or unexpected validation error on GET /orders

Likely cause: Query parameters were passed incorrectly. Note that URLs containing & must be quoted in the shell to prevent the shell from interpreting & as a background operator.

Fix: Wrap the full URL in single quotes when using curl: curl 'https://api.example.com/orders?status=paid&limit=10'.