Use requests.post(url, json=payload, timeout=10) if the API expects a JSON body. Requests serializes the value and sets the JSON content type. For form fields, use data= when the API expects form encoding. Verify the endpoint and body format in the service documentation before sending a request that creates or changes records.
When to use json= and when to use data=
An inventory API might expect a JSON object with keys such as label and quantity. This function shows how the Python dictionary becomes the request body. Use a test endpoint you control or have permission to use.
import requests
def create_item(api_url, label, quantity):
payload = {"label": label, "quantity": quantity}
response = requests.post(
api_url,
json=payload,
timeout=(3.05, 10),
)
response.raise_for_status()
return response
Requests serializes the object and sets the content type for JSON. A dictionary passed to data= is normally form encoded instead. A file upload can have another contract, such as multipart form data. Choose one mechanism to match that API rather than sending the same object in several parameters.
Check the outcome that the application needs
A creation endpoint may return 201 and a resource ID. A 202 response can tell you the server accepted a job that still needs to run. A 204 response has no body. Check the response status and body against the service's documentation before deciding whether there is an ID to save, a job to follow, or nothing to parse.
For an input error, preserve the service error category in a safe local diagnostic. Do not print the entire request body if it contains personal data. A small error message with a request identifier helps someone trace what happened without exposing every field.
Handle an uncertain result carefully
If a connection breaks after submission, a client can receive no response even though the service processed the operation. Repeating the POST blindly can create a second item. Check whether the API documents an idempotency key, a client-generated identifier, or a reconciliation step. Use the documented mechanism. Adding a header with an invented name will not make a service recognize retries.
Keep distinct records for confirmed success, confirmed failure, and unknown outcome. For example, a job that hit a timeout can report it could not confirm creation. That is accurate even if a later lookup finds the item.
Make the API's input rules visible in your caller
A quantity can be valid JSON and still reject the service's business rules. For example, a negative number is a valid JSON value. An inventory endpoint may require a zero or greater integer. Preserve the difference between serialization and validation. Check the public contract and make the error clear enough for the caller to correct its input.
If the service supports sending an envelope around a list, read the documented response for partially accepted batches. The application should not infer that every item was accepted from a single 200 response. In a test environment, send a small batch with one intentionally invalid value only if that case is supported for testing. Inspect whether the documented behavior is to reject the whole batch or report per-item outcomes.
Decide who should confirm a mutation
A tool can present the proposed fields and target before submitting a change. A client that runs unattended needs an explicit rule about which items it may create and how it avoids duplication. The same API call can support either workflow. Document when the request is issued and which record proves it was accepted. A log saying a request was sent is not confirmation that the item exists.
Review the request before connecting it to real work
Exercise the payload building and response handling with synthetic cases. Then run one allowed test operation and verify the result using the service's normal interface. Check what happens to the resulting test data and remove it through approved tools if required.
Keep authentication in a private configuration and follow the service's access documentation. Review which host receives the request, which fields are transmitted, and which results can be retried. A small POST helper becomes reliable when these decisions are visible and a failed response leaves an interpretable state.