StackShare Enterprise API Docs

Getting Started

This is a GraphQL API. We recommend using Insomnia or GraphiQL as your GraphQL API client.

On macOS, you can respectively install them with brew install --cask insomnia or brew install --cask graphiql.

Authentication

You will have been given an API key. To authenticate your requests to the server, place this token in the Authorization header like this:

Authorization: Bearer <api_key>

GraphQL endpoint

The GraphQL endpoint is:

https://graphql.stackshare.io/private_stackshare/graphql

Executing Queries

Here is an example query that you can copy/paste in your API client:

query {
  tools(first: 2) {
    edges {
      node {
        name
      }
    }
  }
}

The above query is getting the first 2 tools from your company's stacks and selecting their name field (see the Tool doc for the full list of fields you can select).

The response from the server looks like this:

{
  "data": {
    "tools": {
      "edges": [
        {
          "node": {
            "name": "Docker"
          }
        },
        {
          "node": {
            "name": "JavaScript"
          }
        }
      ]
    }
  }
}

For development and troubleshooting, it is helpful to know what a GraphQL web request actually looks like. It is a POST request made with a JSON body, as shown below:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{"query": "{ tools(first: 2) { edges { node { name } } } }"}' \
  https://graphql.stackshare.io/private_stackshare/graphql

To see what our API has to offer, see the Queries and Mutations sections in the sidebar on the left. Happy querying! 🚀

Pagination & Counting

Paginated results use GraphQL connections.

For example, the tools query returns paginated Tool objects via a ToolConnection. Let's get the first page of 10 tools, with total count, page information, and tool names:

{
  tools(first: 10) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        name
      }
    }
  }
}

The response looks like this:

{
  "data": {
    "tools": {
      "totalCount": 829,
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "MTA"
      },
      "edges": [
        {
          "node": {
            "name": "Docker"
          }
        },
        {
          "node": {
            "name": "JavaScript"
          }
        },
        ...
      ]
    }
  }
}

We can see that:

the total number of tools, regardless of pagination, is in the totalCount field
in the pageInfo field, there is a next page (hasNextPage) and a reference to that next page (endCursor)
the actual tool data is in the edges field

To get the second page, we need to set the after parameter to the endCursor value from the previous request, like so:

{
  tools(first: 10, after: "MTA") {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        name
      }
    }
  }
}

When hasNextPage becomes false, there are no more pages to query.

By default, 10 items are returned per page. The maximum items you can retrieve per page is 100.