8. Exercise: Workflow for API Creators
10m

Exercise: Creating a new API

🎯 Goal: Create a new simple API locally and publish the changes to update our 🎯 Goal: Understand API to integrate into custom workflows and requirements

Using a template

rover template is a great starting point if you don't have one

First, we're going to start with a simple mocked template that you can clone and setup:

rover template use


#or


git clone https://github.com/apollographql/subgraph-template-typescript-apollo-server-boilerplate my-repo
cd my-repo
npm install
npm start

Create a new supergraph.yaml file and we're going to add some configuration for our new API service:

federation_version: 2
subgraphs:
  hello:
    routing_url: http://localhost:4001
    schema:
      file: ./schema.graphql

Now start up rover dev with your and this new config to add your new API to the locally running .

APOLLO_KEY=service:Retail-Supergraph-6bnnli:0l............Vg APOLLO_GRAPH_REF=Retail-Supergraph-6bnnli@current rover dev --graph-ref Retail-Supergraph-6bnnli@current --supergraph-config supergraph.yaml```

Now we would go about changing our schema to be what we actually need for our change; a breaking change to our products. Change the contents of the schema.graphql file to be this:

type User @key(fields: "id") {
  id: ID!


  """
  The users login username
  """
  username: String!


  """
  Get the list of last session id of user activity
  """
  previousSessions: [ID!]


  """
  Total saved loyalty points and rewards
  """
  loyaltyPoints: Int


  """
  Saved payment methods that can be used to submit orders
  """
  paymentMethods: [PaymentMethod]


  """
  The users previous purchases
  """
  orders: [Order]


  """
  The users current saved shipping address
  """
  shippingAddress: String
}


"""
A saved payment option for an user
"""
type PaymentMethod {
  id: ID!
  name: String
  description: String
  type: PaymentType!
}


"""
A fix set of payment types that we accept
"""
enum PaymentType {
  CREDIT_CARD
  DEBIT_CARD
  BANK_ACCOUNT
}


type Order @key(fields: "id", resolvable: false) {
  id: ID!
}

One of the important workflows is being able to check if a change your would impact production traffic. We can use the rover subgraph check command to see if our changes would impact production traffic against the insight usage in . You can run from your terminal, but this would normally be integrated into your CI/CD workflows:

rover subgraph check Retail-Supergraph-6bnnli@current --schema ./schema.graphql

You should see a error because we have removed the Query.user which is currently being used in production. This is an example of developers can check changes locally and you can have a pull request fail due to a breaking change. These tools enable you to create a self-service workflow for shipping updates to your platform APIs

Building

Like we saw at the end of the previous section, our update when any changes are published into . This is what is done with the rover subgraph publish command which looks exactly the same as the check command you just ran. The only difference is you can also provide a --routing-url option for the location of the new API or if you want to have something like blue-green deploys.

Integrating GraphOS schema pipeline anywhere

The rover CLI is actually just a client for the GraphOS Platform API. This means you can simply make to our API for any of the features rover uses.

Integrating

😅 with great power comes great responsibility, please don't publish changes to the workshop graph - you are an admin

Solutions

Previous

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.