At the root of the schema, you'll find the core objects that power TakeShape projects.
shapesA Shape is a schema object for structuring and storing data from one or more sources, including the TakeShape data store and connected services.
All shapes exist inside the root-level schema object shapes. Each shape is defined by an object key, an id field, and a name field.
name field should always be the same. This value is used in @ref and @mapping annotations; during the automatic generation of queries and mutations for models, like getShape and getShapeList; and is available as _shapeName on an item.id is a used in the shapeIds property of a @relationship and available as _shapeId on an item.The additional field title is used for presenting the shape in UIs.
Shapes contain an inner schema that configures their properties. Like the rest of the schema, this is designed to be a flattened object. Instead of deeply nested and potentially repeated objects, complex structures are achieved through linking with the @refargs and @relationship annotations.
Shape schemas also have a number of underscore prefixed properties that are automatically managed by TakeShape, such as _created and _updated to record the dates shape items are created and edited.
Shapes can also be extended by use of the allOf keyword. This is most useful when working with remote shapes where you can't modify the original shape, but want to add specific properties. See the example below.
Guides
‣
servicesBy connecting new Services to your project schema, you can add shapes, queries, and mutations from 3rd party sources to your API in TakeShape. This allows you to mesh together exactly the API you need to interact with all of the services your app or business depends upon.
Services use an encrypted configuration to keep auth tokens secret. For this reason, services can only be added to a schema through the web client or through the Admin API.
Guides
Adding GraphQL services, shapes, and queries
Adding REST services, shapes, and queries
queries & mutationsQueries and Mutations in your schema map directly to queries and mutations in your project's GraphQL API. In the schema you can define behaviors for these queries and mutations that span one or more services.
Though they describe different functionality, query and mutation objects both have the same set of properties:
shape: string (required)
Specifies which shape is returned by the query or mutation. The shape can refer to a shape in the schema's "shapes" object or a shape that's available on a service schema (we provide an example of a remote shape reference below).resolver: object (required)
Configures the resolver for your query or mutation.
Learn more about resolversdescription: string (optional)
Provides more detail about what the query or mutation is for. This will be displayed in the automatically-generated GraphQL API docs (optional)args: string (optional)
The args field specifies the name of a Shape for the input arguments required by your resolver. If your query does not need any input, you can omit this.Guides
Working with Queries & Mutations
formsForms ****define a visual interface for editing Shapes.
workflowsWorkflows describe the status of a shape item. Every schema starts with a default workflow with two steps, Disabled and Enabled.
Each step can be configured to have a custom name, title, and color. Steps have a live value to indicate whether items in the state should be returned in list queries.
Developer plans are limited to the default workflow. Professional projects can add new workflows and specify them on a per-shape basis. Learn more about professional plans
localesLocales are an array of IETF language tags your project supports for internationalization. By default, projects have a single en locale which is also the default locale.
Developer projects are limited to 2 locales. Professional projects can have up to 5 locales. Learn more about professional plans
Also at the root of the schema are a number of properties that are mainly used by the web client and API. As a schema author, you should almost never need to edit these fields.
versionThis is the revision number of your schema. Every time your project schema is updated, this value should be incremented. The version is used to identify versions in your schema's history.
projectIdThe ID of the TakeShape project this schema belongs to.
defaultLocaleThe locale that should be preferred when creating new Shape items. This must be an entry in the **locales** array.
authorThe ID of the TakeShape user who created the schema.
createdThe date the schema was created
updatedThe date the schema was last updated
schemaVersionThe version of the schema format your project is using. We increase the version as we make breaking changes to the schema format. The current version is 3.
apiVersionThe version of the TakeShape API your project is using. We increase the version as we make breaking changes to the API endpoints.The current version is 2.
A resolver is a function that executes when a query or mutation is called, or a shape field is accessed. A resolver is required on queries & mutations, and may be used in a shape property.
export interface BasicResolver {
name: string;
service: string;
argsMapping?: DirectiveMap | DirectiveConfig[];
resultsMapping?: DirectiveMap | DirectiveConfig[];
options?: {
model?: string;
[k: string]: any;
};
}
name The name of the built-in resolver your query or mutation should use. There's three types of built-in resolvers:
service
Specifies the endpoint and authentication configuration the resolver should use, identified by a connected service's slug. For example:
graphql:rick-andmortyrest:open-weathertakeshape:localoptions (optional)
Each type of resolver—GraphQL, REST, or TakeShape—takes its own set of options. These are specified in the Built-in resolvers section below.
argsMapping (optional)
Maps a query's input args to the input expected by the service's endpoint.
resultsMapping (optional)
Maps a service endpoint's response results to the expected shape of the query's response.
Argument and results mappings are defined using directives, which are a composable pipelines of function. Each directive is a two-element array, which combines an operation like "get" or "set" with a configuration.
TakeShape provides a library of built-in resolvers when you're writing your own queries and mutations.
When writing queries and mutations that use a GraphQL service, you'll have access to two resolvers that execute queries and mutations on the connected service.
graphql:query
graphql:mutation
Options:
fieldName The name of the query or mutation on the GraphQL service's schema that the resolver will use
selectionSet (optional)
Useful when doing mutation composition, this allows the schema author to override or modify the selectionSet of fieldName
ttl (optional)
Only applicable to queries, this setting enables basic TTL caching of queries
When writing queries and mutations that use a REST service, you'll have access to resolvers that execute many of the standard HTTP request methods on the connected service.
rest:get
rest:head
rest:post
rest:put
rest:patch
rest:delete
Options:
path
The resource path your resolver is accessing on the REST service. This is appended to the service's base path when making requests.
The path can use variable values, like /character/{id}. This variable would be set using the argsMapping key pathParams.id
ttl (optional)
This setting enables basic TTL caching to requests
There are also TakeShape-specific resolvers that allow you to execute common CRUD actions on model-annotated shapes.
takeshape:get
takeshape:list
takeshape:create
takeshape:update
takeshape:delete
takeshape:duplicate
Options:
model
The name of the TakeShape model this resolver should act upon.
A resolver can compose multiple resolvers in a pipeline of resolution steps.
Each resolver in the compose array is executed serially and referable by its id property.
id propertyOn any resolver step you can provide an id property which gives you a stable, easy-to-use identifier for use in your expressions and directives.
currentQuery contextThe context of a query is available for use in directives and expressions. The context is comprised of: