Setting up your environment
Get your account information
Contact your API Connect for GraphQL administrator for the account name, the domain, and the keys.
Your administrator provides the following keys for your account:
- Account name: Your organization shares a single account, which serves as a user name when you log in.
- Domain: The domain where API Connect for GraphQL is installed, which you specify when you log in.
- Admin key: Grants access to upload, modify, configure, and deploy APIs.
When you log in to API Connect for GraphQL, you will be prompted for the admin key instead of a password.
- API key: Grants access to consume GraphQL APIs and query the endpoints.
The API key is required for connecting to the APIs deployed to API Connect for GraphQL. Pass this key through the
Authorization
header in the following format:Authorization: apikey {APIKEY}
Install the CLI
Use the CLI (command-line interface) to work with API Connect for GraphQL and your GraphQL APIs. The CLI is supported on Windows, Mac, and Linux.
- Install the Node.js
runtime.
Node
is required for running the CLI. - Install the CLI by running the following
command:
npm install -g stepzen
If you receive EACCES errors with installing globally, see the Resolving EACCES permissions errors when installing packages globally in the
Node
documentation. - (Optional) Customize the default CLI configuration as explained in Configuring the CLI.
Log in to API Connect for GraphQL with the CLI.
API Connect for GraphQL does not provide a graphical UI. Instead, you use the CLI to work with the service.
- Log in by running the following
command:
stepzen login -a <account> <domain>
where:
<account>
is the username of the account you want to log in to.<domain>
is the domain or the region where API Connect for GraphQL is installed or hosted. For example,eu-central-a.ibm.stepzen.net
orus-east-a.ibm.stepzen.net
For example, if the account is
production
, and the domain isgraphserver.apps.my-rosa-cluster.abcd.p1
, then the login command looks like the following example:stepzen login -a production graphserver.apps.my-rosa-cluster.abcd.p1
Consider another example where the account is
beaverdam
and API Connect for GraphQL is hosted in theeu-central-a.ibm.stepzen.net
region. In this scenario, the login command is:stepzen login -a beaverdam graphserver eu-central-a.ibm.stepzen.net
- When prompted, enter the admin key for the account.
https://stepzen.<domain>
https://stepzen.graphserver.apps.my-rosa-cluster.abcd.p1
Create a workspace directory for your project
When you are ready to starting building GraphQL APIs, change to the appropriate workspace directory to ensure your artifacts are stored in the correct location.
- Create a workspace directory where you will work on a particular project.
Name the directory whatever you like.
- Change to the new workspace directory.
- Run the following command to initialize the workspace:
stepzen init
Get your API endpoint URL
The API endpoint URL is based on your account name, domain, and API name.
- In your initialized workspace directory, run the following
command:
stepzen start
- Note down the API endpoint URL that displays in the response.
For example, if your account name is
production
, your domain isexample.com
, and your API name isharping-cat
, you will see the following output:Your API url is https://production.example.com/api/harping-cat/__graphql
When you deploy an API, it is uploaded to this endpoint.
(Optional) Install Docker for local development
For instructions on setting up Docker for use with API Connect for GraphQL, see Using Docker for local API development.
(Optional) Log in to an on-premises Introspection service
By default, API Connect for GraphQL uses a public introspection service, hosted by IBM. If your administrator deployed an on-premises introspection service, pass it as a parameter to the login command as in the following example:
stepzen login -a <account> <domain> --introspection stepzen-introspection.<domain>
While you remained logged in, all introspection requests (stepzen import
commands) are directed your on-premises service instead of to the public service.