The best way to quickly understand results returned by the Marvel Comics API is to test actual calls using the interactive documentation. The documentation presented here provides a deeper dive into API result structure and organization.
Results returned by the API endpoints have the same general format, no matter which entity type the endpoint returns. Every successful call will return a wrapper object, which contains metadata about the call and a container object, which displays pagination information and an array of the results returned by this call. This pattern is consistent even if you are requesting a single object.
Wrappers for successful calls have the following format:
attribute | type | description |
---|---|---|
code | int | The HTTP status code of the returned result |
status | string | A string description of the call status |
data | A container | The results returned by the call |
etag | string | A digest value of the content |
copyright | string | The copyright notice for the returned result |
attributionText | string | The attribution notice for this result |
attributionHTML | string | An HTML representation of the attribution notice for this result |
Containers have this format:
attribute | type | description |
---|---|---|
offset | int | The requested offset (skipped results) of the call |
limit | int | The requested result limit |
total | int | The total number of results available |
count | int | The total number of results returned by this call |
results | Array[entity type] | The list of entities returned by the call |
Putting it together, a typical result will look like this:
{
"code": 200,
"status": "Ok",
"etag": "f0fbae65eb2f8f28bdeea0a29be8749a4e67acb3",
"data": {
"offset": 0,
"limit": 20,
"total": 30920,
"count": 20,
"results": [{array of objects}}]
}
}
If a call to an API endpoint fails, the API will return an error object with the following format:
attribute | type | description |
---|---|---|
code | int | the http status code of the error |
status | string | a description of the error |
The API will also send an HTTP status code equal to the code attribute of the returned error object.