API HTTP standards




HTTP Methods


The API supports 4 HTTP methods for interacting with resources:


GET

Make a GET request to retrieve data. GET requests will never cause an update or change to your data because they are read-only.


POST

Use a POST request to create new resources. For example, make a POST request to the user's endpoint where the body of your request JSON is a new user.


PATCH

Make a PATCH request to update a resource. With PATCH requests, you only need to provide the data you want to change.


PUT

Use a PUT request to create or update a resource.



Making requests



The ioCash API only supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, most POST and PATCH requests require a valid JSON object for the body. Thus, All requests should supply the Accept: application/json header. POST requests must specify the Content-Type: application/json header. Response bodies are as well JSON encoded.




Parameters


There are 3 main categories of parameters for each endpoint in the ioCash API: path, request body, and response body. This section offers an overview of the 3.

Path parameters


In an API url, we include resource names and unique identifiers to help you figure out how to structure your requests. Resource names are immutable, but resource identifiers are required, so you need to replace them with real values from your ioCash client account. Let’s look at an example:

/api/v1/public/wallets/{walletId}/movements/{movementId}

In this request example, there is one primary resource wallets and a secondary one movements. There ar also 2 resource identifiers that you need to replace with real values of your ioCash account: walletId and movementId.

Request body parameters


For PATCH, and POST requests, you may need to include a request body in JSON format. The user operations docs and the wallet operations docs show you all the available request parameters for each endpoint, including the required fields.

Response body parameters


Every API call response includes headers and an optional JSON-formatted body.





HTTP Status Codes



In this section you can rapidly review all the HTTP status codes you can get with the IoCash API so that you can get back to work as fast as possible.

Success codes


Http Status Error code Description
200 OK Standard response for successful HTTP requests. The actual response will depend on the request method used.
201 Created A new resource has been created.
202 Accepted The process has not finished e.g. user creation . Usually when the process is asynchronous.

Client errors codes


Http Status Error code Description
400 Bad Request The request cannot be fulfilled due to bad syntax. Usually used for request fields validations.
401 Unauthorized This error will show anytime you make a request without having being previously authorized for using the API..
403 Forbidden If authentication credentials were provided in the request, the server considers them insufficient to grant access.
404 Not Found The origin server did not find a current representation for the target resource
409 Conflict The request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict.

Server error codes


Http Status Error code Description
500 Internal Server Error A generic error message, given when no more specific message is suitable. Should not be thrown programatically.
503 Service Unavailable The server is currently down and unable to handle the request