Common API behavior
The following constraints apply to all requests and responses that occur in Mergeflow's RESTful API.
Transport Protocol
This API is based on the Hypertext Transfer Protocol, version 1.1 (RFC 2616).
Media Types
Within this API all resource representations are encoded in JSON (RFC 7159). The internet media type is application/json. All dates and times within the JSON are represented in the ISO 8601 format.
Request Headers
Beside the basic required HTTP headers like Content-Length and Host several specific HTTP headers are used as described in the following table:
| Name | Supported Values | Description | Required |
| Accept | Comma-delimited list of internet media types | Indicates to the server what media types the client is prepared to accept. This API version only supports application/json. | Recommended |
| Content-Type | Media type describing the request message body | Describes the representation and syntax of the request body. This API version only supports text/plain. | Recommended |
| MergeflowNet-Api-Auth-Key | GUID | User specific GUID that is used to authenticate a request against the API. | Yes |
Response Headers
Beside the basic required HTTP headers like Content-Length several specific HTTP headers are used as described in the following table:
| Name | Supported Values | Description |
| Content-Type | Media type describing the response message body. | Describes the representation and syntax of the response message body. This API version only supports application/json. |
Standard HTTP Status Codes
The API will return standard HTTP response codes as described in the following table:| HTTP Status | Description |
| 200 OK | The request was successfully completed. |
| 400 Bad Request | The request could not be processed because it contains missing or invalid information, or the specification version is not supported. The response message body will contain more detailed information. |
| 404 Not Found | The request specified a URI of a resource that does not exist or is not publicly available. |
| 500 Internal Server Error | The server encountered an unexpected condition which prevented it from fulfilling the request. |
| 503 Service Unavailable | The server is currently unable to handle the request due to temporary overloading or maintenance of the server. |
Error Response Message Bodies
If a response is returned with an error status code (400-499 or 500-599), the server returns a response message body containing an error data model with the error code and a message describing what went wrong. The text value of such messages might be used, for example, to communicate with a human user of the client side application.
Example:
