HTTP Requests and Responses

Each endpoint behaves differently depending on the request method that is used in a request to it.

To see what is accepted by a particular endpoint, make an OPTIONS request.

http OPTIONS https://apps.dataplicity.com/

curl -X OPTIONS https://apps.dataplicity.com

The response will inform you of what you can do on that endpoint:

HTTP/1.1 200 OK
    Allow: POST, DELETE, OPTIONS
    Content-Type: application/json
    ...

    {
        "actions": {
            "POST": {...}
        },
        "description": "...",
        "name": "...",
        "parses": ["application/json"],
        "renders": ["application/json"]
    }

In this case, the Allow header tells you that the accepted request types are POST, DELETE, and OPTIONS.

The description and name keys contain brief documentation of the endpoint. The description may contain newline characters encoded as \n.

If an action (PUT, POST, etc) requires particular data in the body of the request, it will provide information about the information that it expects.

Responses will use the standard HTTP response codes where possible. Of particular interest will be:

• 200 OK. All went well. The body of the response contains information about the state of a resource.

• 201 Created. The data you sent was used to create a resource. The body of the response will contain information about the created resource.

• 202 Accepted. Your request was accepted for processing. This usually means that the requested action will be attempted, but does not guarantee that it will complete successfully.

• 204 No Content. Your request was successful, but there is no appropriate data to respond with.

• 301 Moved Permanently. This denotes that a resource is not in the location that you requested. Perhaps you forgot to add a trailing / onto the URL? The Location header should guide you to a new location.

• 400 Bad Request. The data you've sent across does not conform to expectations. The body of the response will detail what went wrong.

• 401 Unauthorized. Authentication is required, but has not been provided.

• 403 Forbidden. Access denied. Authentication will not help.

• 404 Not Found. You have tried to access a resource that doesn't exist or you do not have access to.

• 405 Method Not Allowed. The request method you used (eg: POST) is not allowed for this resource. You should see the acceptable methods for a particular endpoint by inspecting the Allow header.