Submarine GraphQL API

• It’s a specification The spec determines the validity of the schema on the API server. The schema determines the validity of client calls.

• It’s strongly typed The schema defines an API's type system and all object relationships.

• It’s introspective A client can query a GraphQL schema for details about itself.

• It’s hierarchical The shape of a GraphQL call mirrors the shape of the JSON data it returns. Nested fields let you query for and receive only the data you specify in a single round trip.

• It’s an application layer GraphQL is not a storage model or a database query language. The graph refers to graph structures defined in the schema, where nodes define objects and edges define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored.

plain text
https://api.getsubmarine.com/graphql

• If you’re making requests on behalf of a Shopify store, you will need a channel token. This can be retrieved from the Submarine UI:

• If you’re making requests on behalf of a Shopify customer, you will need a customer token. See XXX for details about how to generate such a token.

plain text
curl -H "Authorization: Bearer API_KEY" -X POST -d " \
 { \
   \"query\": \"query { channel { identifier } }\" \
 } \
" https://api.getsubmarine.com/graphql

• adding 1 for pageInfo and each of its sub-selections;

• adding 1 for count, totalCount or total;

• adding 1 for the connection field itself; and

• multiplying the complexity of other fields by the largest possible page size, which is the greater of first: or last:.

graphql
query {
  channel {                       # +1
    identifier                    # +1
    presaleCampaigns(first: 10) { # +1
			edges {
        node {                    # +10 (+1, multiplied by `first:` above)
          id                      # +10 (ditto)
        }
      }
      pageInfo {                 # +1
        endCursor                # +1
      }
      totalCount                 # +1
    }
  }
}

json
{
  "errors": [
    {
      "message": "Query has complexity of 1023, which exceeds max complexity of 1000"
    }
  ]
}

json
{
  "errors": [
    {
      "message": "Query has depth of 22, which exceeds max depth of 20"
    }
  ]
}

• identifying a customer to update;

• specifying what products define a presale campaign;

• retrieving a campaign order group.

plain text
gid://submarine/Customer/018436f0-5a23-12dd-882e-89af29dfb5d6

plain text
gid://external/Customer/6204442509552

graphql
query {
  channel
    identifiers
  }
}

json
{
  "errors": [
    {
      "message": "Cannot query field 'identifiers' on type 'Channel'. Did you mean 'identifier'?",
      "locations": [
        {
          "line": 1,
          "column": 32
        }
      ],
      "path": [
        "query channel",
        "channel",
        "identifiers"
      ],
      "extensions": {
        "code": "undefinedField",
        "typeName": "Channel",
        "fieldName": "identifiers"
      }    
    }
  ]
}

As mentioned in Submarine GraphQL API above, Submarine performs some analysis of each request to determine whether it fits within our fair-use policy. Should any of those validations fail, a top-level error will be surfaced.

graphql
query {
  channel(id: "gid://submarine/Channel/01827ac5-2dd1-b0a3-cd1b-45c3a0e942db") {
    identifier
  }
}

json
{
  "data": {
    "channel": null
  }
}

graphql
mutation customerCreate($input: CustomerCreateInput!) {
  customerCreate(input: $input) {
    customer {
      id
    }
    userErrors {
      field
      message
    }
  }
}

json
{
  "input": {
    "externalId": "6204442509552"
  }
}

• the external ID has already been taken by another customer; and

• Submarine requires that one of email of phone is provided.

json
{
  "data": {
    "customerCreate": {
      "customer": null,
      "userErrors": [
        {
          "field": [
            "externalId"
          ],
          "message": "External ID has already been taken"
        },
        {
          "field": [
            "contact"
          ],
          "message": "Either email or phone needs to be present"
        }
      ]
    }
  }
}

graphql
query customers {
  customers(first: 2, after: "Mg") {
    edges {
      node {
        id
      }
      cursor
    }
    pageInfo	{
      endCursor	
    }
  }
}

json
{
  "data": {
    "customers": {
      "edges": [
        {
          "node": {
            "id": "gid://submarine/Customer/0184e067-17cd-b04c-d830-1bf60e33e30b"
          },
          "cursor": "Mw"
        },
        {
          "node": {
            "id": "gid://submarine/Customer/0184e072-e87a-1519-6026-0bc25dbd9109"
          },
          "cursor": "NA"
        }
      ],
      "pageInfo": {
        "endCursor": "NA"
      }
    }
  }
}