The Best Collected Details on the GraphQL Specification, Section 3

References https://spec.graphql.org specifically October 2021 Edition.

This is the second part (the first part covered the overview and language of GraphQL) to a collection of notes and details, think of this as the cliff notes of the GraphQL Spec. Onward to section 3 of the spec…

The GraphQL type system is described in section 3 of the specification. Per the specification itself,

The GraphQl Type system describes the capabilities of a GraphQL service and is used to determine if a requested operation is valid, to guarantee the type of response results, and describes the input types of variables to determine if values provided at request time are valid.

This feature of the specification for the GraphQL language uses Interface Definition Language (IDL) to describe the type system. This can be used by tools to provide utility function as client code genration or boot-strapping. In a lot of the services and products around GraphQL like AppSync, Hasura, and others you’ll see this specifically in action. Tools that only execute requests can only allow TypeSystemDocument and disallow ExecuteDefintion or TypeSystemExtension to prevent extensions of the type system. If you do this be sure to provide a descriptive error for consumers of your data!

Continue reading “The Best Collected Details on the GraphQL Specification, Section 3”

Getting an Existing GraphQL `schema.graphql` of Your API

Let’s say you’ve built out your GraphQL API. Now let’s say you want a schema.graphql file but for some reason you don’t have your repo or for some reason it’s not immediately available. What to do? Here are two tools to get a quick schema of your GraphQL API by pointing them at your API and letting them introspect against it!

Prerequisite

For both of these you’ll need to have NPM installed, which I’ll just assume you do if you’re dealing with GraphQL. If you don’t, head on out and get NPM and Node.js installed for good measure, and per my suggestion do yourself a favor and pick a version manager. I generally use nvm, check out details on install NVM here.

graphqurl

Install with the following command.

npm install -g graphqurl
Continue reading “Getting an Existing GraphQL `schema.graphql` of Your API”

The Best Collected Details on the GraphQL Specification – Overview & Language

GraphQL, a query language and execution engine is described in this specification based on capabilities and requirements of data models for client-server applications. This article details and elaborates on the specification, the features and capabilities of GraphQL and implementations. I hope this collection of details around the GraphQL Specification can be used as a reference and launch point into learning about GraphQL use, implementation – server and client side – and ongoing references during future specification additions or changes!

Continue reading “The Best Collected Details on the GraphQL Specification – Overview & Language”

A Go Repo & Some Go Code

Wrapped up another Twitch stream (follow here) and streamed live via YouTube where the video is now (subscribe here, video here). However the more interesting part IMHO was where I broke down a few key parts of the application building features around file writes, reads, JSON marshalling, and some other functionality. I also put together a repo of the code I put together here on Github (code shown and explained below). I dove into this topic in the later part of the stream which I’ve time tagged below. For the full timeline and the rest of the video just watch from the beginning of the video. I do make some progress working on Colligere, but I’ll cover that topic in a subsequent blog entry and Twitch stream.

  • 1:32:40 – Creating a new application with Jetbrains Goland to show off how to use the Go core libraries around the user, JSON, and some basic file creation and writing.
  • 1:36:40 – At this point I start adding some basic code to pull the current user and collect some information about that user.
  • 1:40:42 – I extract the error code using the Goland refactoring feature and setup a func check() for error checking. That cleans up the inline code a bit.
  • 1:43:10 – Here I add to the user data retrieved some environment variables to that list of collected data. I also cover again, as I have a number of times, how the environment variables are pulled in IDE versus user session versus out of IDE.
  • 1:47:46 – Now I add a file exists check and start working on that logic.
  • 1:48:56 – Props to Edd Turtle on a solid site on Go. Here’s the blog entry, and respectively the path to more of Edd’s material @ https://golangcode.com/. Also, Edd seems like a good guy to follow @eddturtle.
  • 2:01:33 – Starting the JSON Work here to marshal and unmarshall.
  • 2:26:33 – At this point I push the code up to Github (repo here) using the built in Goland VCS features. I realize I’ve named the repo “adron” by accident so I rename it, close Goland, and then clone the code back down locally with Goland’s VCS features. It’s kind of interesting to see Goland go through the 2-factor auth for this too.
  • 2:58:56 – The Seattle Thrashing Code outtro!

There were a few notes I took during the session with my collected links and references for things I looked up. Those included the following:

The code for the Github repo, ended in this state. Just a single main.go file, which shows how to use several features of Go and capabilities of the core libraries.

[sourcecode language=”javascript”]
package main

import (
“encoding/json”
“io/ioutil”
“log”
“os”
“os/user”
“strconv”
)

type UserInformation struct {
Name string `json:”name”`
UserId int64 `json:”userid”`
GroupId int64 `json:”groupid”`
HomeDir string `json:”homedir”`
UserName string `json:”username”`
GroupIds []string `json:”groupids”`
GoPath string `json:”gopath”`
EnvVar string `json:”environmentvariable”`
}

func main() {
currentUser, err := user.Current()
check(err)
changeDataForMarshalling(currentUser)
}

func changeDataForMarshalling(currentUser *user.User) {
groupsIds, err := currentUser.GroupIds()
check(err)
userId, err := strconv.ParseInt(currentUser.Uid, 6, 64)
check(err)
groupId, err := strconv.ParseInt(currentUser.Gid, 6, 64)
check(err)

workingUserInformation := &UserInformation{
Name: currentUser.Name,
UserId: userId,
GroupId: groupId,
HomeDir: currentUser.HomeDir,
UserName: currentUser.Username,
GroupIds: groupsIds,
GoPath: os.Getenv(“GOPATH”),
EnvVar: os.Getenv(“NEW_STRING_ENVIRONMENT_VARIABLE”),
}

resultingUserInformation, _ := json.Marshal(workingUserInformation)

filename := “collected_values.json”
if _, err := os.Stat(filename); os.IsNotExist(err) {
writeFileContents(err, filename, string(resultingUserInformation))
} else {
newUserInformation, err := openFileMakeChanges(filename)
writeFileContents(err, filename, newUserInformation)
}
}

func openFileMakeChanges(filename string) (string, error) {
jsonFile, err := os.Open(filename)
check(err)
defer jsonFile.Close()
var changingUserInformation UserInformation
byteValue, _ := ioutil.ReadAll(jsonFile)
json.Unmarshal(byteValue, &changingUserInformation)
changingUserInformation.Name = “Adron Hall”
changingUserInformation.GoPath = “/where/is/the/goland”
newUserInformation, _ := json.Marshal(changingUserInformation)
return string(newUserInformation), err
}

func writeFileContents(err error, filename string, text string) {
f, err := os.OpenFile(filename, os.O_CREATE|os.O_WRONLY, 0600)
check(err)
defer f.Close()

if _, err = f.WriteString(text); err != nil {
panic(err)
}
}

func check(err error) {
if err != nil {
log.Fatal(err)
}
}
[/sourcecode]

The import section includes several core libraries for the application “encoding/json”, “io/ioutil”, “log”, “os”, “os/user”, and “strconv”. Then I’ve got a structure declared that I use throughout the code with various fields.

Then just for the heck of it I created a changeDataForMarshalling function and passed in userInfo and parsed the string results of gid and uid to int data types. From there the remaining values are passed in then marshalled to JSON and written to a file, depending on if it’s a new file or existing. The writing however I broke out to a function dubbed writeFileContents. Definitely some more refactoring and tweaking to really make it functional and usable, but shows easily what strconv, marshalling, and other features of these core libraries do. This code provides some examples on what functionality Colligere will use to read in schema configuration, edit, and save that schema. More about that in the next Twitch few streams.

History of Symphonize.js – JavaScript Client Pivot to Data Generation Library

…the history of symphonize.js So Far!

NOTE: If you just want to check out the code bits, scroll down to the sub-title #symphonize #hacking. Also important to note I’m putting the library through a fairly big refactor at the moment so that everything aligns with the documentation that I’ve recently created. So many things may not be implemented, but we’re moving toward v0.1.0, which will be a functional implementation of the library available via npm based entirely on the documentation and specs that I outline after the history.

A Short History

I started the symphonize.js project back on the 1st of November. Originally I started the project as a client driver library for Orchestrate.io, but within a day Chris Molozian commented and pointed out that there was already a client driver library for Orchestrate.io available that Steve Kaliski (Github @sjkaliski and Twitter @stevekaliski and http://stevekaliski.com/) had coded called logically orchestrate.js. Since this was available I did a pivot to symphonize.js being a data generation project instead.

The comment that enabled symphonize.js to pivot from client driver to data generation library.
The comment that made me realize symphonize.js should pivot from client driver to data generation library.

The Official Start of Symphonize.js

After that start and quick pivot I posted a blog with Orchestrate.io titled “Test Data Builder Symphonize.js With Chance.js (1/3)” to officially start the project. In that post I covered key value and graph basics, with a dive into using chance.js and orchestrate.js with examples. Near the same time I also posted a related blog on publishing an NPM module, which is the deployment focus of Symphonize.js.

Reasons Reasoning

There are two main reasons why I chose Orchestrate.io and a data generation library as the two things I wanted to combine. The first, is I knew the orchestrate.io team and really dug what they were building. I wanted to work with it and check out how well it would work for my use cases in the future. The ability to go sit down, discuss with them what they were building was great (which I interviewed Matt Heitzenroder @roder that you can watch Orchestrate.io, Stop Dealing With the Database Infrastructure!) The second reason is that my own startup that I’m co-founding with Aaron Gray (@agray) needed to use key value and graph data storage of some type, somewhere. Orchestrate.io looked like a perfect fit. After some research, giving it a go, it fit very well into what we are building.

CRUD, cURL Hacking & Next Steps

Early December I knocked out two support articles about testing APIs with cURL in Some JavaScript API Coding With Restify & Express & Hacking it With cURL …Segment #1 (with some Webstorm to boot) and Some JavaScript API Coding With Restify & Express & Hacking it With cURL …Segment #2 and an article on the Orchestrate.io Blog for part 2 of that series titled Symphonize Some Create, Read, Update & Delete [CRUD] via Orchestrate.js (2/3).

December then rolled into the standard holiday doldrums and slowdowns. So fast forward to January post a few rounds of beer and good tidings and I got the 3rd in the series published titled Getting Serious With Symphony.js – JavaScript TDD/BDD Coding Practices (3/3). The post doesn’t speak too much to symphony.js usage but instead my efforts to use TDD or BDD practices in trying to write the library.

Slowly I made progress in building the library and finally it’s in a mostly releasable state now. I use this library daily in working with the code base for Deconstructed and imagine I’ll use it ongoing for many other projects. I hope others might be able to find uses for it too and maybe even add capabilities or ideas. Just ping me via Twitter @adron or Github @adron, add an issue on Github and I’ll be happy to accept pull requests for new features, code refactoring, add you to the project or whatever else you’re interested in.

#symphonize #hacking

Now for the nitty gritty. If you’re up for using or contributing to the project check out the symphonize.js github pages site first. It’s got all the information to help get you kick started. However, you can keep reading as I’ve included much of the information there along with the examples from the README.md below.

NOTE: As I mentioned at the top of this blog entry, the funcitonal implementation of code isn’t available via npm just yet, myself and some others are ripping through a good refactor to align the implementation fo the library with the rewritten and newly available documentation – included blow and at the github pages.

How to use this project in one of your projects.

[sourcecode language=”bash”]
npm install symphonize
[/sourcecode]

How to setup this project for development.

First fork the repository located at https://github.com/Adron/symphonize.

[sourcecode language=”javascript”]
git clone git@github.com:YourUserName/symphonize.git
cd symphonize
npm install
[/sourcecode]

Using The Library

The intended usage is to invocate the JavaScript object and then call generate. That’s it, a super simple process. The code would look like this:

[sourcecode language=”javascript”]var Symphonize = require(‘../bin/symphonize’);
var symphonize = new Symphonize();
[/sourcecode]

The basic constructor invocation like this utilizes the generate.json file to generate data from. To inject the json configuration programmatically just inject the json configuration information via the constructor.

[sourcecode language=”javascript”]
var configJson = {"schema":"keyvalue"};

var Symphonize = require(‘../bin/symphonize’);
var symphonize = new Symphonize();
[/sourcecode]

Once the Symphonize data generator has been created call the generate() method as shown.

[sourcecode language=”javascript”]
symphonize.generate();
[/sourcecode]

That’s basically it. But you say, it’s supposed to do X, Y or Z. Well that’s where the json configuration data comes into play. In the configuration data you can set the data fields and what they’ll generate, what type of data will be generated, the specific schema, how many records to create and more.

generate.json

The library comes with the generate.json file already setup with a working example. Currently the generation file looks like this:

[sourcecode language=”javascript”]
{
"schema": "keyvalue", /* keyvalue, graph, event, geo */
"count": 20, /* X values to generate. */
"write_source": "console", /* console, orchestrateio and whatever other data sources that might come up. */
"fields": {
/* generates a random name. */
"fieldName": "name",
/* generates a random dice roll of a d20. */
"fieldTwo": "d20",
/* A single lorum ipsum random statement is genereated. */
"fieldSentence": "sentence",
/* A random guid is generated. */
"fieldGuid": "guid" }
}
[/sourcecode]

Configuration File Definitions

Each of the configuration options that are available have a default in the configuration file. The default is listed in italics with each definition of the configuration option listed below.

  • schema” : This is used to select what type of data structure type is going to be generated. The default iskeyvalue for this option.
  • count” : This provides the total records that are to be generated by the library. The default is 1 for this option.
  • write_source” : This provides the location to output the generated data to. The default is console for this option.
  • fields” : This is a JSON field within the JSON configuration file that provides configuration options around the fields, number of fields and their respective data to generate. The default is one field, with a default data type of guid. Each of the respective entries in this JSON option is a self contained JSON name and value pair. This then looks simply like this (which is also shown above in part):[sourcecode language=”javascript”]{
    "someBoolean": "boolean",
    "someChar": "character",
    "aFloat": "float",
    "GetAnInt": "integer",
    "fieldTwo": "d20",
    "diceRollD10": "d10",
    "_string": {
    "fieldName": "NameOfFieldForString",
    "length": 5,
    "pool": "abcdefgh"
    },
    "_sentence": {
    "fieldName": "NameOfFiledOfSentences",
    "sentence": "5"
    },
    "fieldGuid": "guid"
    }
    [/sourcecode]
  • Fields Configuration: For each of the fields you can either set the field to a particular data type or leave it empty. If the field name and value pair is left empty then the field defaults to guid. The types of data to generate for fields are listed below. These listed are all simple field and data generation types. More complex nested generation types are listed below under Complex Field Configuration below the simple section.
    • boolean“: This generates a boolean value of true or false.
    • character“: This generates a single character, such as ‘1’, ‘g’ or ‘N’.
    • float“: This generates a float value, similar to something like -211920142886.5024.
    • integer“: This generates an integer value, similar to something like 1, 14 or 24032.
    • d4“: This generates a random integer value based on a dice roll of one four sided dice. The integer range being 1-10.
    • d6“: This generates a random integer value based on a dice roll of one six sided dice. The integer range being 1-10.
    • d8“: This generates a random integer value based on a dice roll of one eight sided dice. The integer range being 1-10.
    • d10“: This generates a random integer value based on a dice roll of one ten sided dice. The integer range being 1-10.
    • d12“: This generates a random integer value based on a dice roll of one twelve sided dice. The integer range being 1-10.
    • d20“: This generates a random integer value based on a dice roll of one twenty sided dice. The integer range being 1-20.
    • d30“: This generates a random integer value based on a dice roll of one thirty sided dice. The integer range being 1-10.
    • d100“: This generates a random integer value based on a dice roll of one hundred sided dice. The integer range being 1-10.
    • guid“: This generates a random globally unique identifier. This value would be similar to ‘F0D8368D-85E2-54FB-73C4-2D60374295E3’, ‘e0aa6c0d-0af3-485d-b31a-21db00922517’ or ‘1627f683-efeb-4db8-8174-a5f2e3378c87’.
  • Complex Field Configuration: Some fields require more complex configuration for data generation, simply because the data needs some baseline of what the range or length of the values need to be. The following list details each of these. It is also important to note that these complex field configurations do not have defaults, each value must be set in the JSON configuration or an error will be thrown detailing that a complex field type wasn’t designated. Each of these complex field types is a JSON name and value parameter. The name is the passed in data type with a preceding underscore ‘_’ to generate with the value having the configuration parameters for that particular data type.
    • _string“: This generates string data based on a length and pool parameters. Required fields for this include fieldNamelength and pool. The JSON would look like this:[sourcecode language=”javascript”]"_string": {
      "fieldName": "NameOfFieldForString",
      "length": 5,
      "pool": "abcdefgh"
      }
      [/sourcecode]

      Samples of the result would look like this for the field; ‘abdef’, ‘hgcde’ or ‘ahdfg’.

    • _hash“: This generates a hash based on the length and upper parameters. Required fields for this included fieldNamelength and upper. The JSON would look like this:[sourcecode language=”javascript”]"_hash": {
      "fieldName": "HashFieldName",
      "length": 25,
      "casing": ‘upper’
      }
      [/sourcecode]

      Samples of the result would look like this for the field: ‘e5162f27da96ed8e1ae51def1ba643b91d2581d8’ or ‘3F2EB3FB85D88984C1EC4F46A3DBE740B5E0E56E’.

    • _name”: This generates a name based on the middle, *middleinitial* and prefix parameters. Required fields for this included fieldNamemiddlemiddle_initial and prefix. The JSON would look like this:[sourcecode language=”javascript”]"_name": {
      "fieldName": "nameFieldName",
      "middle": true,
      "middle_initial": true,
      "prefix": true
      }
      [/sourcecode]

      Samples of the result would look like this for the field: ‘Dafi Vatemi’, ‘Nelgatwu Powuku Heup’, ‘Ezme I Iza’, ‘Doctor Suosat Am’, ‘Mrs. Suosat Am’ or ‘Mr. Suosat Am’.

So that covers the kick start of how eventually you’ll be able to setup, use and generate data. Until then, jump into the project and give us a hand.

After this, more examples on the way, cheers!