GraphQL API Prototype

[Oleg]

GraphQL API Prototype

We are very excited to announce the availability of our experimental GraphQL API prototype.

NOTE: It is a beta version and we recommend to create test space and try prototype in it.

How to try it?

Every space has separate GraphQL API endpoint. The list of available space API endpoints can be found by following the link: {your fibery host}/api/graphql

You will see GraphQL API Explorer after clicking the link for the desired space. You can view the documentation and explore available queries and mutations by clicking Docs in top right corner. It is the place where you can try querying and mutations of your database records.

How to find/list database records

findEntities(params): [Entity]

Finds rows in database. Params consists of database fields/relations filters, offset, limit.

For example:

{
  findBugs(name: {contains: "first"}) {
    id
    name
    state{
      name
    }
    assignees{
      name
    }
  }
}

How to modify/create database records

There are multiple operations available for modifying database records. These operations can be performed for found entities by provided filter or for created records in corresponding database.

Find below an example of operations which can be performed for created record. In this example new bug created, assigned to author of API call, description with content “TBD” is set to bug description.

mutation {
  stories {
    create(name: "Super Bug") {
      message
    }
    assignToMe {
      message
    }
    appendContentToDescription(value: "TBD") {
      message
    }
  }
}

For creating multiple records batch operation command createBatch can be used.

mutation {
  stories {
    createBatch(data: [
      {name: "Bug 1"}
      {name: "Bug 2"}
    ]) {
         entities {
          id
         }
    }
    assignToMe {
      message
    }
    appendContentToDescription(value: "TBD") {
      message
    }
  }
}

Find below the example of operations which can be performed for found records by provided filter as params to root node of mutation. Bugs with word “first” in name are moved into “In Progress” state, sprint is unlinked, found bugs are assigned to author of API call and the owner of found stories is notified.

 mutation {
  bugs(name:{contains: "first"}){
    update(state: {name: {is: "In Progress"}}) {
      message
      entities {
        id
      }
    }
    unlinkSprint {
      message
    }
    assignToMe {
      message
    }
    notifyCreatedBy(subject: "Assigned to Aleh") {
      message
    }
  }
}

We will publish more articles and tutorials about using graphql after the official release. Now we really appreciate your feedback. Ideas, questions or issues are very welcome.

Please let us know about your thoughts.

[rothnic]

I noticed this in the backlog and have been interested to try it out. Not only is it more intuitive to build queries vs the current API, but it could open up interesting use cases with other tooling that supports GraphQL.

I was able to pretty easily query some data within a few seconds of playing around with it. For example, getting all initiatives with their name, then any related ideas and their name.

{
  findInitiatives{
    name,
    ideas{
      name
    }
  }
}

The only thing I can think of is it would be nice to have some examples for quickly leveraging this in a simple HTTP request like you have in the other API docs if you don’t have that already. Or, better yet if there is some way to just copy that to your clipboard for the current query, that could be useful.

Basically, a stubbed out example using curl, fetch (js), requests (python), etc where people can quickly take the query that is working in the graphiql playground, then leverage it in a script.

[Oleg]

Hello, @rothnic

Thanks for feedback. We will add more code samples and documentation later.

By the way rich fields can be retrieved as well in md, text, html or jsonString formats.

{
  findFeatures{
    name,
    description{
      text
    }
  }
}

[rothnic]

Nice, I was curious about that.

One other thing I’d mention that might be a little bit more intuitive is using the explorer extension for graphiql. It was used in another project (maybe Hasura?) I played with a bit and found it useful. I don’t know whether it is complex to setup, maintain, etc though.

GitHub - OneGraph/graphiql-explorer: Explorer plugin for GraphiQL

[Matt_Blais]

I can query a collection’s contents and get a list of entities as expected, but I am not able to query a related entity’s collection. Is this a fundamental limitation?

E.g. “Meeting Notes” has a related “Client”, and “Client” contains a collection of “Projects”

THESE WORK:

{ findClients(limit:1) {
  projects { id name }  
  }
}

{ findMeetingNotes(limit:1) {
  defaultProject{
    id name
  }
}}

THIS DOESN’T WORK:

{ findMeetingNotes(limit:1) {
  client{
    projects{
      id name
    }
  }
}}

"message": "Invalid query.\nCause: Unknown query select expression Organization/Client, {\"q/from\":\"Project/Projects\",\"q/select\":{\"id\":[\"fibery/id\"]},\"q/limit\":1000}.",

[Oleg]

Hello, @Matt_Blais

Thanks for the feedback. We will check, probably it is a bug or it is a limitation of our fibery core and this type of querying will not be possible.

Thanks,
Oleg

[Mikkling]

Really nice!

Is there a plan for what kind of graph capabilities you intend to add to Fibery?

\m/

[Mikkling]

I am trying to query the endpoints from Apollo Studio but i cannot get it to work. I am guessing it is an authentication issue.

Is there a way to access the endpoints from other graphql clients?

[Oleg]

Hello, @Mikkling

You may use other clients. Please configure corresponding auth header for your client:

Authorization: Token YOUR_TOKEN

Please find here how to retrieve auth token and how to add auth header.
Below an example how I configured My WebStorm GraphQL Client:

Thanks,
Oleg

[Mikkling]

Thanks!

I managed to query my endpoints in Insomnia, so now i know it works!

I still cannot get Apollo Explorer to authenticate successfully…

[NWE]

This is very interesting and works great the little I’ve tested.

Should we expect graphQL take over when finished and the ‘old’ api will be redundant?
Even upload and attach files?
(I’m using fibery as a CMS for phones and attach files through the current api when needed)

I agree with the above post about some good examples later on.

[Matt_Blais]

@Oleg
How to update a Rich Text field with GraphQL? Rich Text fields like “description” do not appear in the GraphiQL docs under “update”.

[Oleg]

Hi, @Matt_Blais

Please use one of the following methods to update rich fields (markdown templates are supported):

mutation{
  features(id:{is:"ABC"}) {
    overwriteDescription(value:"rewrite {{NAME}} desc"){message}
    appendContentToDescription(value: "text to append"){message}
    prependContentToDescription(value: "text to prepend"){message}
  }
}

Thanks,
Oleg

[Matt_Blais]

@Oleg
Thanks - is “features(id)” the Rich Text secret?

[Chr1sG]

@Matt_Blais

Thanks - is “features(id)” the Rich Text secret?

No, it’s just an example of how to choose which entity to update.
In this case, we’re updating a feature whose Id equals “ABC”.

[Oleg]

Right, Feature is database, Description is a name of rich field

[Matt_Blais]

So overwriteX prependX and appendX exist for every Rich Text field “X”?

[Oleg]

Hi, @Matt_Blais

It is correct. overwriteX, prependX and appendX exist for every Rich Text field “X”

[Matt_Blais]

Is only markdown supported for updating Rich Text fields via GraphQL?

I am trying to clone an entity, including duplicating the Rich Text Description, but if I must use Markdown then much of the formatting is lost (e.g. colors). I would like to use HTML format, since it preserves the formatting.

[Oleg]

Hi, @Matt_Blais

It is only markdown for now. But thanks for feedback. I will add the feature about extending with HTML support. Can not give exact estimates, but we will implement it in future.

Thanks,
Oleg