Result Structure

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

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:

attributetypedescription
code int The HTTP status code of the returned result
status string A string description of the call status
data A containerThe 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:

attributetypedescription
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}}]
                                }
                            }

Errors

If a call to an API endpoint fails, the API will return an error object with the following format:

attributetypedescription
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.