49. Overview

49. Overview
Prev	Part X. REST API Guide	Next

Spring Cloud Data Flow provides a REST API allowing you to access all aspects of the server. In fact the Spring Cloud Data Flow Shell is a first-class consumer of that API.

	Tip
	If you plan on using the REST API using Java, please also consider using the provided Java client (DataflowTemplate) that uses the REST API internally.

49.1 HTTP verbs

Spring Cloud Data Flow tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb	Usage
`GET`	Used to retrieve a resource
`POST`	Used to create a new resource
`PUT`	Used to update an existing resource, including partial updates. Also used for resources that imply the concept of `restarts` such as Tasks.
`DELETE`	Used to delete an existing resource

49.2 HTTP status codes

RESTful note tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code	Usage
`200 OK`	The request completed successfully
`201 Created`	A new resource has been created successfully. The resource’s URI is available from the response’s `Location` header
`204 No Content`	An update to an existing resource has been applied successfully
`400 Bad Request`	The request was malformed. The response body will include an error providing further information
`404 Not Found`	The requested resource did not exist
`409 Conflict`	The requested resource already exists, e.g. the task already exists or the stream was already being deployed
`422 Unprocessable Entity`	Returned in cases the Job Execution cannot be stopped or restarted

49.3 Headers

Every response has the following header(s):

Name	Description
`Content-Type`	The Content-Type of the payload, e.g. `application/hal+json`

49.4 Errors

Path	Type	Description
`error`	`String`	The HTTP error that occurred, e.g. `Bad Request`
`message`	`String`	A description of the cause of the error
`path`	`String`	The path to which the request was made
`status`	`Number`	The HTTP status code, e.g. `400`
`timestamp`	`String`	The time, in milliseconds, at which the error occurred

49.5 Hypermedia

Spring Cloud Data Flow uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application from resource to resource Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate.