JSON – JavaScript Object Notation

JSON (JavaScript Object Notation), a lightweight data-interchange format. It’s relatively easy to read for us humans, which is nice, and is a subset of the JavaScript Programming Language Standard (ECMA-262 3rd Edition – December 1999).

JSON is a text format, and even though it’s a subset of JavaScript, is language independent. The conventions are of the C-family of languages like C, C++, C#, Java, JavaScript, and others.

There are two structures to JSON; a collection of name value pairs and ordered lists of values. For more details check out the organization. A few examples for reference.

A simple JSON object.

{
    "name":"John", 
    "age":30, 
    "car":null
}

An array of JSON objects.

[
    {
        color: "red",
        value: "#f00"
    },
    {
        color: "green",
        value: "#0f0"
    },
    {
        color: "blue",
        value: "#00f"
    },
    {
        color: "cyan",
        value: "#0ff"
    },
    {
        color: "magenta",
        value: "#f0f"
    },
    {
        color: "yellow",
        value: "#ff0"
    },
    {
        color: "black",
        value: "#000"
    }
]

A JSON object using a list.

{  
    "name":"John",  
    "age":30,  
    "cars":["Ford", "BMW", "Fiat"]  
}

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.