GraphQL is the ideal language for developers using aiWARE's data API. Its clean, open, and unified structure compliments the application's data and operations needs.
GraphQL is a query language. It lets you format queries that specify what information you want to send or receive, using a formal schema defined by the API provider. GraphQL has several benefits over a traditional REST API:
- Users control exactly what information they retrieve with each operation.
- The schema is self-documenting, which reduces errors and time wasted from bad input.
- The Sandbox user interface lets users explore the schema and all the information available to them.
Below is starting information for GraphQL learners, GraphQL experts, and some GraphQL practices.
Also see:
GraphQL learners
If you're new to GraphQL, learn more at GraphQL.org. In addition to background information, they also offer an Introduction to GraphQL.
GraphQL experts
If you have experience working with GraphQL APIs, you can start exploring the date API in the following ways:
GraphQL best practices
- Use the online Sandbox to explore the schema, make ad hoc queries to find data, and test and debug queries and mutations for your applications.
- You can request as many fields as you want on a given type — including the top-level
query. You can make multiple queries in a single request. - GraphQL lets you structure complex queries that retrieve, aggregate, and marshal large amounts of data. Use with caution. Complex queries over large data sets can affect performance.
- You can retrieve the same field twice in order to apply different parameters, using aliases. For example:
query {
firstUser: user(name:"smith") {
...
}
secondUser: user(name:"jones") {
...
}
thirdUser: user(id:"...") {
...
}
}
- GraphQL supports interfaces, which define common fields for a set of types, and unions, which specify a grouping of types with no common fields. A field that uses an interface or union can include any of several types. All types that implement a given interface have common fields that can be requested in the usual way. However, to request a type-specific field you must use a fragment.
This example uses TemporalDataObject, which accepts an interface, Metadata in its metadata field. We'll ask for a common field, name, along with some fields that are specific to Program.
Example
{
temporalDataObjects(limit: 30) {
records {
id
metadata {
name
...on Program {
image
liveImage
}
}
}
}
}
Result
{
"data": {
"temporalDataObjects": {
"records": [
{
"id": "21098452",
"metadata": [],
"status": "uploaded",
"startDateTime": 0,
"stopDateTime": 0
},
{
"id": "21098441",
"metadata": [],
"status": null,
"startDateTime": 0,
"stopDateTime": 0
},
{
"id": "21098183",
"metadata": [
{
"name": "CloneData",
"__typename": "CloneData"
},
{
"__typename": "FileData",
"name": "FileData"
},
{
"__typename": "JSONObject",
"name": "veritone-permissions"
},
{
"name": "Program",
"__typename": "Program",
"image": "",
"liveImage": "https://s3.amazonaws.com/dev-veritone-ugc/demo_temp%2FprogramImageURL%2Fo8poaodeRpmUJBNK3tKT_cw.png"
}
]
}
]
}
}
}
