Working with a REST API: the GitHub case study

Glamorous Toolkit allows you to work with REST APIs out of the box. Here, we take a look at how we can play with the GitHub REST API. Although the case study is specific to GitHub, the approach is essentially the same to work with other REST APIs. If you prefer a video introduction, have a look at Exploring the GitHub REST API in 7' on YouTube.

Overview of the approach

A REST API allows you to download information about a software system in some format, typically JSON. The raw data is interesting, but is cumbersome to work with. The moldable development approach in GT to turn this data into an “explainable system” is to model the domain by taking the raw data and wrap them into domain entities. Then, we iteratively add tiny, contextual tools to these entities ( i.e., contextual views, actions and searches) that make the domain entities into a live, explorable model answering questions about the domain — an explainable system . In the case of the GitHub REST API, we obtain raw JSON data about an organization in GitHub (such as feenk), about its repos , their contributors , their commit events , and so on. We turn each of these into live, explorable domain entities by wrapping the raw data and adding contextual tools. Let's see this in action ...

Extracting the raw data

GitHub offers a REST API to explore data about the repositories hosted by any given organization. As a case study we start from JSON content located at https://api.github.com/orgs/feenkcom which looks like this:

The first thing we do is to retrieve that JSON programmatically:

url := 'https://api.github.com/orgs/feenkcom'.
  

json := ZnClient new get: url.
  

Now, that's just a string. We never really want to work with a string. We'd rather parse it:

dictionary := STONJSON fromString: json.
  

Wrapping the data

Parsing the JSON string produces a dictionary. That's already better, but still not quite what we want. We want a custom experience for that outcome. To this end, we wrap the data as a first class object:

GhOrganization new rawData: dictionary.
  

Once we have a dedicated object the inspector gets the opportunity to present contextual views. For example, the repositories list is described in GhOrganization>>#gtReposFor: gtReposFor: aView <gtView> ^ aView columnedList title: 'Repositories'; priority: 40; items: [ self repos ]; column: 'Repo' text: #name; column: 'Description' text: #description; column: 'Open issues' text: #numberOfOpenIssues; column: 'License' text: #licenseName .

Now, try exploring. For example, what happens when you double click on a repository? Notice how you can navigate from the feenk organization to its repositories , and from there to individual contributors , their GitHub events and issues .