Documentation for Umbraco Heartcore GraphQL API
The GraphQL API can be accessed on https://graphql.umbraco.io
, it accepts POST requests with the content type application/json
. The body must be JSON and contain a query
field with the query as a string and an optional variables
field containing the variables.
In order to access the data for your Umbraco Heartcore project you need to provide a project identifier (Project Alias) via an HTTP Header or a Querystring parameter.
The Project Alias is an HTTP friendly version of the Project Name under your Umbraco Cloud account.
By default the GraphQL API is not protected. This can be enabled through the Backoffice, where API keys for each user in the Backoffice is also managed.
To access the GraphQL API the user must have access to the Content
section and have the Browse Node
permission.
The GraphQL API supports fetching draft content, this can be done by passing a preview
argument to the root query fields.
Fetching draft content requires an API Key to be passed with the request.
Information on how the GraphQL schema is generated, reserved names and built-in custom types.
A list of all the built-in Umbraco Property Editors and their GraphQL types.
Documentation on how to filter and order collections with the GraphQL API.
Documentation for Umbraco Heartcore GraphQL property editors and their types
Below is a list of all the supported built-in Umbraco Property Editors and their GraphQL types. The type may depend on the configuration of the specific Property Editor.
Below is a list of property editors which is not supported in GraphQL and will not be present in the generated schema.
Documentation for GraphQL filtering in Umbraco Heartcore.
The GraphQL API allows for filtering and ordering root and traversion collections (ancestors, children and descendants).
For information on the different filters available and how the filter and order types are generated see Schema Generation.
To start filtering the content, an where
argument can be passed to the collection query. E.g. to find all products where it's price is higher than 100 we can write the following query.
Filters can be combined with AND
and OR
, e.g. if we want to find all content on level 2
or 3
that is updated after 2020-03-13
we write the following query.
Or if we want to get all of type person which names does not start with t
we can write the following query.
We can combine AND
, OR
and NOT
in a single query e.g. if we wan't to get all content on level 1
or 2
that does not start with b
or j
we can write the following query.
Filtering can also be applied to types returning Content
and Media
, e.g. if we want all content of type Post
where the author name is Rasmus
, we can write the following query.
The collection can also return draft content by passing the preview
argument with a boolean to the query. Draft content is always protected and requires an Api-Key.
Lets say we want to show all our products that haven't been published, we can write the following query.
The collection can also be sorted by passing the orderBy
argument to the query.
If orderBy
is not specified the collections are ordered by path
which is the order they appear in, in the Umbraco Backoffice tree.
Lets say we want to show all our products ordered by price in ascending order, we can write the following query.
We can even add multiple values to the orderBy
argument to order by multiple fields. E.g. if we want to order products by price and then by name, we write the following query.
We can also limit the number of results returned by paging. To achieve this one can use first
and after
to do forward paging and last
and before
to do backward paging.
The cursor can be obtained by including the cursor
field on an edge e.g. to get the first 50
products we can write the following query.
We can then use the cursor
from the last item to get items that appear after that one. We can also request the PageInfo
object which holds information on the start and end cursors and if there are more pages.
first
can only be used in combination withafter
, and last
can only used with before
.
Also hasNextPage
is only populated when doing forward paging andasPreviousPage
is populated when doing backward paging.
Everything shown up until now can be combined in a single query, the following query will get the first 50 products where the price
is greater than 100
and order the result in ascending order by price
and then by name
.
Documentation for Umbraco Heartcore GraphQL schema generation
The GraphQL schema is generated from the Content Types upon creation, and it is generated when a Content Type or a Data Type is changed.
The type name is the Content Type's alias in Pascal Case, e.g. if a Content Type has an alias of product
it's GraphQL type name would be Product
.
The types generated depends on how the Content Types are configured.
A Connection and an Edge type will also be generated, these are used when quering Content of a specific type.
The Query
type is the entry to the GraphQL API. By default it contains two fields, one to get a single Content item by ID
or url
and one to get all Content.
For each Document Type that is not used as a Composition or marked as an Element Type, two fields will be generated on the Query
type. One for getting a single Content item by either it's ID
or url
and a field for getting all Content of that specific type.
GraphQL requires that type names are unique. If a Content Type will collide with one of the reserved names the type will be excluded from generation.
The same applies to Properties. If a Property alias is a reserved one it will also be excluded from generation.
List of reserved type names, these cannot be used as an alias
for Content Types.
The GraphQL type name is the Content Type alias
converted to Pascal Case.
BigInt
BlockGrid
BlockGridArea
BlockGridItem
BlockListItem
Byte
Content
Date
DateTime
DateTimeOffset
Decimal
DecimalRange
Element
Guid
HTML
ImageCropAnchor
ImageCropFormat
ImageCropMode
ImageCropper
ImageCropperCrop
ImageCropperCropCoordinates
ImageCropperFocalPoint
ImageCropRatioMode
JSON
Link
LinkType
Long
Media
MediaConnection
MediaEdge
Milliseconds
OurUmbracoGMaps
OurUmbracoGMapsAddress
OurUmbracoGMapsCoordinate
OurUmbracoGMapsMapConfig
OurUmbracoGMapsMapType
PageInfo
PickedColor
Query
SByte
Seconds
Short
UInt
ULong
Uri
UShort
List of reserved Element Type Property names, these cannot be used as a Property alias
on an Element Type.
contentTypeAlias
List of reserved Content Type Property names, these cannot be used as a Property alias
on a Content Type.
ancestors
children
contentTypeAlias
createDate
descendants
id
level
name
parent
content
parentId
sortOrder
updateDate
url
List of reserved Media Type Property names, these cannot be used as a Property alias
on a Media Type.
ancestors
children
createDate
descendants
id
level
mediaTypeAlias
name
parent
sortOrder
updateDate
url
The Umbraco Heartcore GraphQL schema contains some default types, below you can find a list of these types.
Query
Output
Query
Output
Query
Output
Query
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
Query:
Output:
For all Document Types a FilterInput
type is generated. The name is the type name postfixed by FilterInput
e.g. given a type named Product
the name will be ProductFilterInput
.
To filter the allContent
field, ancestors
, children
and descendants
connections the ContentFilterInput
is used.
All filter inputs for Content Types will also have the default fields.
Filtering is possible only on non-complex Property Editors like Text Area and Label. Filtering on more complex types like Content Picker and Multi-node Tree Picker has to be done client-side.
For fields returning String
the following filter fields are generated.
Given the following type:
The following type will be generated, incl. the fields from the ContentFilterInput
.
For fields returning Int
or Decimal
the following filters are generated.
The type is either Int
or Decimal
depending on the output type.
Given the following type:
The following type will be generated, incl. the fields from the ContentFilterInput
.
For types returning Boolean
the following filters are generated.
Given the following type:
The following type will be generated, incl. the fields from the ContentFilterInput
.
For types returning DateTime
the following filters are generated.
Given the following type:
The following type will be generated, incl. the fields from the ContentFilterInput
.
For types returning Media
the MediaFilterInput
is used.
For types returning [Decimal]
, [Int]
or [String]
the following filters are generated.
The type is [Decimal]
, [Int]
or [String]
depending on the output type
Given the following type:
The following type will be generated, incl. the fields from the ContentFilterInput
.
The result can be ordered by specifying a value for the orderBy
argument.
An OrderBy
type is generated for all Document Types. The name is the type name postfixed by OrderByInput
e.g. given a type named Product
the name will be ProductOrderByInput
.
Fields returning DateTime
, Decimal
, Boolean
, Int
or String
can be used to order by.
To filter the allContent
field, ancestors
, children
and descendants
connections the ContentOrderBy
is used.
All order by inputs for Content Types will also have the default fields.
The following type will be generated, incl. the fields from the ContentOrderByInput
.
If you don't specify any order the data returned will be ordered by the path they appear in, in the Umbraco Backoffice tree.
If a Content Type is inherited from or used as a it will be generated as an interface
If the Document Type is marked as an Element Type it will implement the interface
All other Content Types will implement either the or the interface, they will also implement all their Composition interfaces.
All properties on a Content Type is generated as a field on the GraphQL type. See the page for which types the editors are returning.
If a property is marked as , a culture
argument is added to that field. The argument is optional and will fallback to the parent fields culture or the default culture if none is specified.
The page contains a list of all the Property Editors and which GraphQL types they return.
For types returning Content
the is used.