In addition to telling epic stories of misunderstood teenagers swinging between the skyscrapers of Manhattan, comics have a robust and complex data model and consist of several different entity types. Before we get into the specifics of the API results we'll explain what these entities are and how they relate to each other.
(If you are interested in comics data structures and making comics more accessible generally, join Marvel in participating in the proposal process for schema.org and Biblex extensions for web schemas.)
Entities returned by the API will have two representations: a full view and a summary view. The full view is returned by requests to a resource endpoint, and summaries are returned when a resource is referenced by a full resource. For example, a call to the comics endpoint http://gateway.marvel.com/v1/public/comics
returns full views of comics and summaries of other entities such as creators which created the comic, characters which appear in it and the series in which the comic belongs.
We will explain the full representations of entities more in-depth below - they will vary from entity type to entity type.
Summary views will always contain a resourceURI, which points to the full representation of the referenced entity, and a name, for convenience. Some summary representations will additionally have a field describing its type or the relationship between the returned entity and the referenced entity.
You can expect that any result returned by an endpoint to have a full set of fields, but some fields may have empty values. For example, a string attribute may return an empty string or null, but the field will always be present in the returned representation.
Full schemas for each endpoint are also available in the interactive documentation.
While each entity type returned by an endpoint has a distinct structure, many will have components which have a common structure.
URLs are references to web pages or deep links into applications. (When present in a resultset, it is preferred that you use these to link back to Marvel.) Many resources will have more than one representation on the web so URLs are generally presented as an array of URL resources. URLs are modeled as follows:
attribute | type | description |
---|---|---|
type | string | A text identifier for the URL. |
url | string | A full URL (including scheme, domain, and path). |
Text objects are bits of descriptive text which are attached to an entity. They have the following properties:
attribute | type | description |
---|---|---|
type | string | The string description of the text object (e.g. solicit text, preview text, etc.). |
language | string | A language code denoting which language the text object is written in. |
text | string | The text of the text object. |
Resource URIs are references to the representation of a resource within the API. Every resource and resource summary will have a resource URI attribute.
Resource lists are collections of summary views within the context of another entity type. For example, the list of creators attached to a comic would be presented as resource list inside the full representation of that comic. Resource lists have the following format:
attribute | type | description |
---|---|---|
available | int | The number of total available resources in this list |
returned | int | The number of resources returned in this resource list (up to 20). |
collectionURI | string | The path to the list of full view representations of the items in this resource list. |
items | Array[entity summary representations] | A list of summary views of the items in this resource list. |
Requests to the collectionURI will return full representations of the entities in the resource list. For example, the uri http://gateway.marvel.com/v1/public/creators/32
will return a representation of a particular creator. That creator representation will have an issues attribute which is a resource list of issues that he or she worked on. A call to the resource list's collection URI http://gateway.marvel.com/v1/public/creators/32/comics
will return a set of full representations of comics, filtered by the creator with id of 32.
Images are represented as a partial path and an extension. See the guide to images for information about how to construct full paths to image files.
attribute | type | description |
---|---|---|
path | string | The directory path of to the image. |
extension | string | The file extension for the image. |
attribute | type | description |
---|---|---|
id | int | The unique ID of the character resource. |
name | string | The name of the character. |
description | string | A short bio or description of the character. |
modified | Date | The date the resource was most recently modified. |
resourceURI | string | The canonical URL identifier for this resource. |
urls | Array[Url] | A set of public web site URLs for the resource. |
thumbnail | Image | The representative image for this character. |
comics | ResourceList | A resource list containing comics which feature this character. |
stories | ResourceList | A resource list of stories in which this character appears. |
events | ResourceList | A resource list of events in which this character appears. |
series | ResourceList | A resource list of series in which this character appears. |
attribute | type | description |
---|---|---|
id | int | The unique ID of the comic resource. |
digitalId | int | The ID of the digital comic representation of this comic. Will be 0 if the comic is not available digitally. |
title | string | The canonical title of the comic. |
issueNumber | int | The number of the issue in the series (will generally be 0 for collection formats). |
variantDescription | string | If the issue is a variant (e.g. an alternate cover, second printing, or director's cut), a text description of the variant. |
description | string | The preferred description of the comic. |
modified | Date | The date the resource was most recently modified. |
isbn | string | The ISBN for the comic (generally only populated for collection formats). |
upc | string | The UPC barcode number for the comic (generally only populated for periodical formats). |
diamondCode | string | The Diamond code for the comic. |
ean | string | The EAN barcode for the comic. |
issn | string | The ISSN barcode for the comic. |
format | string | The publication format of the comic e.g. comic, hardcover, trade paperback. |
pageCount | int | The number of story pages in the comic. |
textObjects | Array[TextObject] | A set of descriptive text blurbs for the comic. |
resourceURI | string | The canonical URL identifier for this resource. |
urls | Array[Url] | A set of public web site URLs for the resource. |
series | SeriesSummary | A summary representation of the series to which this comic belongs. |
variants | Array[ComicSummary] | A list of variant issues for this comic (includes the "original" issue if the current issue is a variant). |
collections | Array[ComicSummary] | A list of collections which include this comic (will generally be empty if the comic's format is a collection). |
collectedIssues | Array[ComicSummary] | A list of issues collected in this comic (will generally be empty for periodical formats such as "comic" or "magazine"). |
dates | Array[ComicDate] | A list of key dates for this comic. |
prices | Array[ComicPrice] | A list of prices for this comic. |
thumbnail | Image | The representative image for this comic. |
images | Array[Image] | A list of promotional images associated with this comic. |
creators | ResourceList | A resource list containing the creators associated with this comic. |
characters | ResourceList | A resource list containing the characters which appear in this comic. |
stories | ResourceList | A resource list containing the stories which appear in this comic. |
events | ResourceList | A resource list containing the events in which this comic appears. |
attribute | type | description |
---|---|---|
id | int | The unique ID of the creator resource. |
firstName | string | The first name of the creator. |
middleName | string | The middle name of the creator. |
lastName | string | The last name of the creator. |
suffix | string | The suffix or honorific for the creator. |
fullName | string | The full name of the creator (a space-separated concatenation of the above four fields). |
modified | Date | The date the resource was most recently modified. |
resourceURI | string | The canonical URL identifier for this resource. |
urls | Array[Url] | A set of public web site URLs for the resource. |
thumbnail | Image | The representative image for this creator. |
series | ResourceList | A resource list containing the series which feature work by this creator. |
stories | ResourceList | A resource list containing the stories which feature work by this creator. |
comics | ResourceList | A resource list containing the comics which feature work by this creator. |
events | ResourceList | A resource list containing the events which feature work by this creator. |
attribute | type | description |
---|---|---|
id | int | The unique ID of the event resource. |
title | stding | The title of the event. |
description | stding | A description of the event. |
resourceURI | stding | The canonical URL identifier for this resource. |
urls | Array[Url] | A set of public web site URLs for the event. |
modified | Date | The date the resource was most recently modified. |
start | Date | The date of publication of the first issue in this event. |
end | Date | The date of publication of the last issue in this event. |
thumbnail | Image | The representative image for this event. |
comics | ResourceList | A resource list containing the comics in this event. |
stories | ResourceList | A resource list containing the stories in this event. |
series | ResourceList | A resource list containing the series in this event. |
characters | ResourceList | A resource list containing the characters which appear in this event. |
creators | ResourceList | A resource list containing creators whose work appears in this event. |
next | EventSummary | A summary representation of the event which follows this event. |
previous | EventSummary | A summary representation of the event which preceded this event. |
attribute | type | description |
---|---|---|
id | int | The unique ID of the series resource. |
title | string | The canonical title of the series. |
description | string | A description of the series. |
resourceURI | string | The canonical URL identifier for this resource. |
urls | Array[Url] | A set of public web site URLs for the resource. |
startYear | int | The first year of publication for the series. |
endYear | int | The last year of publication for the series (conventionally, 2099 for ongoing series). |
rating | string | The age-appropriateness rating for the series. |
modified | Date | The date the resource was most recently modified. |
thumbnail | Image | The representative image for this series. |
comics | ResourceList | A resource list containing comics in this series. |
stories | ResourceList | A resource list containing stories which occur in comics in this series. |
events | ResourceList | A resource list containing events which take place in comics in this series. |
characters | ResourceList | A resource list containing characters which appear in comics in this series. |
creators | ResourceList | A resource list of creators whose work appears in comics in this series. |
next | SeriesSummary | A summary representation of the series which follows this series. |
previous | SeriesSummary | A summary representation of the series which preceded this series. |
attribute | type | description |
---|---|---|
id | int | The unique ID of the story resource. |
title | string | The story title. |
description | string | A short description of the story. |
resourceURI | string | The canonical URL identifier for this resource. |
type | string | The story type e.g. interior story, cover, text story. |
modified | Date | The date the resource was most recently modified. |
thumbnail | Image | The representative image for this story. |
comics | ComicList | A resource list containing comics in which this story takes place. |
series | SeriesList | A resource list containing series in which this story appears. |
events | EventList | A resource list of the events in which this story appears. |
characters | CharacterList | A resource list of characters which appear in this story. |
creators | CreatorList | A resource list of creators who worked on this story. |
originalissue | ComicSummary | A summary representation of the issue in which this story was originally published. |