WHAT YOU’LL LEARN
- how to quickly create a functional API package
Before you start this tutorial, make sure that you have Webiny installed and to read our Introduction tutorial.
The API scaffold is our boilerplate GraphQL API that works out of the box without you needing to actually write any code. It will enable you to create, update and delete the data in the database and fetch it via get and list API endpoints. In this article we will go through the process of generating the code.
The command you will run is
yarn webiny scaffold, and you run it from the project root.
You will get a set of simple questions to answer and, in the end, an API package will be generated.
Also note that in this tutorial we will use
CarManufacturer as our data model name.
Run the scaffold command and follow the questions. Select the
GraphQL API package option and let's go through all the questions in detail:
This is the name of your API data model, so type it in.
As mentioned before, we will use
CarManufacturer in this tutorial.
The GraphQL queries, mutations, responses, and variable names in the code will use this value in singular and plural, kebab-case, camel-case or some other form.
The name value is also used to create both the defaults for the package location and the package name.
The initial data model has 3 fields (
isNice) to show you how to structure your data model.
Validation of the data model name allows only a-z and A-Z. You can name your model all lowercase or all uppercase. It is up to you - but try to keep it in pascal-case.
A full location of the package, where the package files will be generated, from the root of the project.
The value given in the previous question is used to create the default package location.
We think it is best to organize your packages in
packages directory, so by default it is set into that directory, but you can type whatever location you want.
To learn more about Webiny's project organization, checkout this article.
The default value is
packages/car-manufacturers/api, and notice that the data model name
CarManufacturer is in plural and kebab-cased.
The package name that you will reference to in the code.
As in the location step, the value from the first question is used to create the default package name.
The default value is
@car-manufacturers/api as we like scoping packages. You can set it to what ever you want, providing it is passing the validation.
Generated code contains:
GraphQLSchemaPluginplugin type which defines the GraphQL schema and resolvers.
src/configuration.tswith the configuration for DynamoDB table, Elasticsearch DynamoDB stream table and Elasticsearch index.
src/es.tswith helpers to build the Elasticsearch query out of the GraphQL query arguments.
src/types.tswith interfaces for resolvers, application context, arguments.
__tests__/useGqlHandler.tswith the setup of the test runners.
__tests__/graphql/carManufacturers.tswith GraphQL queries and mutations to be run.
__tests__/crud.test.tswith the tests for the resolvers.
In the generated code we provide some basic Elasticsearch functionality. Although the DynamoDB is the database the data is being stored to, it does not provide a lot of search capabilities so we introduced the Elasticsearch.
If you do not want to use it you will need to modify the code a bit for it to work without the Elasticsearch.
If you want to use the Elasticsearch functionality, that is provided with the generated code, you must run a GraphQL install mutation described in the information after the code was generated. This will create the Elasticsearch index for your data.
The API scaffold generates initial GraphQL API tests for you. As you add or remove functionality from the code, tests should reflect those changes, so you can be sure that API is working as intended.
You can run tests locally with command
ELASTICSEARCH_PORT=9200 LOCAL_ELASTICSEARCH=true yarn test packages/car-manufacturers/api or
yarn test packages/car-manufacturers/api, if you removed the Elasticsearch.
Tests are Jest based and files must end in
.test.ts to be run.
If you are using the Elasticsearch, you must have local Elasticsearch started for this to work. Port can be something other than 9200.
Generated tests cover CRUD operations and sorting by
In the main GraphQL file you need to import your package and include it in the existing handler.
To use the generated GraphQL API, you must deploy it. To deploy, use the command:
When you deploy the code you will get a URL of the API, it should look something like
GraphQL is accessible on that url with addition of
/graphql, so it is
To create new
CarManufacturer entry, the mutation is:
To list all the
CarManufacturer entries, the query is:
When you want to extend the GraphQL schema you should add it to the
typeDefs property of the
When you add some additional schema, you also must add the resolver for it.
You should add it to the
resolvers property of the
Be aware that the resolver should be under the
CarManufacturerMutation properties, if you added schema into those.
When you make changes to the code, make sure you run
yarn webiny ws run build --folder=packages/car-manufacturers/api to actually compile your code for the deployment.
You can even have a watcher running for your code with
yarn webiny ws run watch --folder=packages/car-manufacturers/api.
Of course, the
folder value is your package location.
Now that you have a functioning API, let's move onto the Admin area.