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:

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

Errors

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.