From 5a0a700a4530b84a108ef4109d9d221b2253d3a4 Mon Sep 17 00:00:00 2001 From: Harshavardhana Date: Fri, 13 Feb 2015 15:20:58 -0800 Subject: [PATCH] Write Error Responses documentation --- docs/api/errors.md | 61 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 14 ++++++++-- docs/introduction.md | 3 +++ mkdocs.yml | 6 +++-- 4 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 docs/api/errors.md create mode 100644 docs/introduction.md diff --git a/docs/api/errors.md b/docs/api/errors.md new file mode 100644 index 000000000..0b11ca906 --- /dev/null +++ b/docs/api/errors.md @@ -0,0 +1,61 @@ +# List of Error Responses + +This section provides information about Minio API errors. XML and JSON results have been prettified for readability. As a result, the Content-Length may not match exactly for both styles + +### Error Codes Table + +The following table lists Minio error codes. + +| Error Code | Description | HTTP Status Code | +|:---------- |:----------- |:----------------:| +| AccessDenied | Access Denied | 403 Forbidden | +| BadDigest | The Content-MD5 you specified did not match what we received. | 400 Bad Request | +| BucketAlreadyExists | The requested bucket name is not available. | 409 Conflict | +| EntityTooSmall | Your proposed upload is smaller than the minimum allowed object size. | 400 Bad Request | +| EntityTooLarge | Your proposed upload exceeds the maximum allowed object size. | 400 Bad Request | +| IncompleteBody | You did not provide the number of bytes specified by the Content-Length HTTP header | 400 Bad Request | +| InternalError | We encountered an internal error. Please try again. | 500 Internal Server Error | +| InvalidAccessKeyId | The access key Id you provided does not exist in our records. | 403 Forbidden | +| InvalidBucketName | The specified bucket is not valid. | 400 Bad Request | +| InvalidDigest | The Content-MD5 you specified is not valid. | 400 Bad Request | +| InvalidRange | The requested range cannot be satisfied. | 416 Requested Range Not Satisfiable | +| MalformedXML | The XML you provided was not well-formed or did not validate against our published schema. | 400 Bad Request | +| MissingContentLength | You must provide the Content-Length HTTP header. | 411 Length Required | +| MissingRequestBodyError | Request body is empty. | 400 Bad Request | +| NoSuchBucket | The specified bucket does not exist. | 404 Not Found | +| NoSuchKey | The specified key does not exist. | 404 Not Found | +| NoSuchUpload | The specified multipart upload does not exist | 404 Not Found | +| NotImplemented | A header you provided implies functionality that is not implemented. | 501 Not Implemented | +| RequestTimeTooSkewed | The difference between the request time and the server's time is too large. | 403 Forbidden | +| SignatureDoesNotMatch | The request signature we calculated does not match the signature you provided. | 403 Forbidden | +| TooManyBuckets | You have attempted to create more buckets than allowed. | 400 Bad Request | +
+ +### REST Error Responses + +When there is an error, the header information contains: + + - Content-Type: application/xml or application/json (Depending on ``Accept`` HTTP header) + - An appropriate 4xx, or 5xx HTTP status code + +The body or the response also contains information about the error. The following sample error response shows the structure of response elements common to all REST error responses. + +``` + + + NoSuchKey + The resource you requested does not exist + /minio-bucket/images.bz2 + ******** + +``` + +The following table explains the REST error response elements + +| Name | Description | +|:---------- |:-----------| +|*Code*| The error code is a string that uniquely identifies an error condition. It is meant to be read and understood by programs that detect and handle errors by type.
*Type: String*
*Ancestor: Error*| +|*Error*| XML container for error.
*Type: Container*
*Ancestor: None*| +|*Message*| The error message contains a generic description of the error condition.
*Type: String*
*Ancestor: Error*| +|*RequestId*| ID of the request associated with the error.
*Type: String*
*Ancestor: Error*| +|*Resource*| The bucket or object for which the error generated.
*Type: String*
*Ancestor: Error*| diff --git a/docs/index.md b/docs/index.md index c1e469b81..6bfbe9045 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,13 @@ -# Minio API +# Welcome to MINIO -## Overview +Welcome to the *Minio API Reference*. It explains the Minio application programming interface. It describes various API operations, related request and response structures, and error codes. + +Minio is an open source object storage released under [Apache license v2](http://www.apache.org/licenses/LICENSE-2.0). It uses ``Rubberband Erasure`` coding to dynamically protect the data. + +## How? + +| Information | Sections | +|:------------- |:-------------:| +| Overview | Minio | +| REST | [Minio API](./api/minio.md) | +| Error List | [Error Codes](./api/errors.md) | diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 000000000..b79146bda --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,3 @@ +# Minio API Reference + +This API reference explains Minio operations, their parameters, responses, and errors. There are separate sections for each API, which include example requests and responses. diff --git a/mkdocs.yml b/mkdocs.yml index 2efa2fd86..2868dc8e2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,9 @@ site_name: Minio Documentation pages: -- ['index.md', Index] -- ['api/minio.md', 'API', 'Minio'] +- ['index.md', Welcome to Minio] +- ['introduction.md', Minio API Reference] +- ['api/minio.md', 'API', 'REST API'] +- ['api/errors.md', 'API', 'Error Responses'] - ['api/manage.md', 'API', 'Management'] - ['architecture.md', 'Architecture', 'Overview'] - ['contributing.md', 'Contributing', 'Overview']