Category

Uncategorized

Getting started with Github GraphQL API

This article is going to give you the basic knowledge necessary to start and develop your very own GraphQL API. This post is part of a series that will cover the full development lifecycle that lead to the creation of an example Github graphQL web app that can be found at the following link http://github-api-example.zelig880.com

GraphQL logo and basic example of query
GraphQL

What is GraphQL?

Before we dive into the actual details of graphQL, I am going to explain what GraphQL is, and what makes it so different from standards Restful API’s.

The actual definition of GraphQL defined on the official website is:


GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

https://graphql.org/

To summarise, GraphQL offer great flexibility compared to standards API’s. Clients are able to define what they want from a server in a single query, without the need to have to jiggle around specific API endpoints.

If for example you would like to create a list of users with their relevant address in a restful API, you will probably have to create two specific endpoint request, one to fetch an User and the second to get the user address.

GraphQL makes client request easier, without the need to make major change on the backend ( the server could still implement a restful API behind GraphQL). The above example can be achieved with a single request in GraphQL in which the client can ask for a “User with address”.

Github GraphQL API

Github character

I have specifically chosen to use the Github GraphQL api, because it is easy to access ( it is quite simple to gain a “personal access token”), and it is free and it provides tools and documentation that support its use.

Personal access tokens

For the scope of this post, you are not actually required to use an access token. I am going to show how to gain one, as it is the first necessary step to be able to move your example query into a real app and it is important to know how to obtain one.

To gain a Personal access token, you must have an account with github ( this can be created for free at the following link: https://github.com)

Obtain the token, after you have created an account, is very simple. You just need to follow this link https://github.com/settings/tokens and click the “Generate new token” button.

Screenshot of the "New personal access token" page form github
New personal access token

A token requires a Description, and a selection of access rules for your token. In this example we are going to query users, and we will therefore select the “User” scope.

Github GraphQL Api explorer

As mentioned above, one of the main advantages of getting started with the Github GraphQL api is provided by the tools provided to developers.

Github offer the ability to query live data, directly in the browser using their Developer explorer.

To access the explorer you just need to follow this link https://developer.github.com/v4/explorer/ and enter your credentials.

Github GraphQL explorer screenshot

The explorer is divided in 4 section:

  1. Query window – Where we are going to define are GraphQL query
  2. Query variable window – This is going to include the dynamic variables accepted by our query
  3. A result window -This is going to show the returned query or a detailed error
  4. Documentation explorer – This window provide extensive documentation on all the API.

Document explorer

Github document explorer
document explorer

The first step is to get familiar with the documentation explorer. This is filled with autocomplete functionality and provides you with a Details, fields list, fields descriptions and a list of Fields that implements the given item. The picture provided shows the result for PageInfo.

Query

If you have ever used a standard Rest API before, you are going to be completely our of your conference zone. GraphQL uses a Json like query. In the following example we are going to search for the first 10, users that match a specific “query variable”.

query SearchTop10Users($user: String!) {
  search(query: $user, type: USER, first: 10) {
    nodes {
      __typename
      ... on User {
        name
        login
        avatarUrl
        url
        bio
      }
    }
  }
}

The query includes:

  • Name: SearchTop10Users
  • Variables: $user: String!
  • Search paramethers: query: $user, type: USER, first: 10
  • Expected return: node, name, login, etc..

As the above query shown, this is very different from conventional APi’s that had defined endpoint (eg. getUser). With GraphQL not only we are able to merge different queries together, but we are also in control on which fields get returned ( eg. just a subset of the user object).

Query variables

Running the above query, is going to result in an error, because our defined variable ($user) has never been defined.

In Gitbut GraphQL variables can easily be defined in the appropriate window. In our case we just need to specify a string for our $user. Variables are passed using a JSON object format.

{ "user": "Zelig" }  

Run it..

We have now completed all the required steps necessary to run our first GraphQL query in the explorer.

Github is going to save all different queries on your profile, providing an useful search. This queries can easily be copied in your application, using the Personal Access token generated above.

Conclusion

This post was aimed at providing you with a very first understanding of GraphQL and its power. Using the Github API has allowed me to understand its basic fundamental, without the need to create a full scaffolding around it queries ( no need to set up a project just to send the queries).

Github extensive documentation on the API, is very helpful to understand the different objects available within graphQL. like nodes and edges ( this may vary between different api’s).

In future posts I am going to implement the above query to create a full Vue application with the use of apollo.js.

How to debug Jasmine-es6 in visual studio code

This article is going to show the configuration required to debug Jasmine-ES6 in Visual studio code.
Jasmine-ES6 is a Helpers and overrides that augment Jasmine for use in an ES6+ environment. It is great when you have a project that you do not want to transpile using babel. And it turned out to be one of the NPM package that was used in one of the latest project in which I was involved.
Due to the nature of the plugin, it is not possible to Debug Jasmine-es6 directly in the browser, but it is possible by using the debug feature provided by Visual Studio Code. The settings that are going to be provided below, will actually work to emulate any NPM command that you are currently using.

Create a debug configuration file in Visual Studio Code.

Visual studio code enables use ( sometimes with the use of extension) to debug almost any coding language (js, c#, php,ect..).

To access the Debug page we need to click the “bug” icon on the left hand menu.

Now that we have accessed the debugging page, we are able to add our configuration. To do so, click on the dropdown next to the Green arrow, like shown in the image below.

Visual Studio Code (VSC) will provide you a list of “predefined” debugging configuration that will support you in completing the setup. In our case we are going to use the “launch program” option.
visual studio code available configuration
Our configuration file will look something like this:
Visual studio Code basic debug file
 
  1. {
  2. "version": "0.2.0",
  3. "configurations": [
  4. {
  5. "type": "node",
  6. "request": "launch",
  7. "name": "Launch Program",
  8. "program": "${workspaceRoot}/app.js"
  9. }
  10. ]
  11. }
The configuration can have multiple entry that can be accessed by the dropdown previously used.

Setting the config

The config requires two main information. The first is the Program that we would like to run, this can actually be changed with whatever program you are currently running from the command line. When writing a command you will probably just use the name of the package ( depending how it is installed ), for example “Jasmine init”.

Node will automatically know that you are looking in reality for a package within the node_modules folder called Jasmine. Unfortunately our Debug configuration file is not that clever and will require you to specify the complete path.
You can use ${workspaceFolder} to select the workspace root, and then form the rest of the path required to reach the entry js file of your package. In the case of Jasmine-es6 the path will look something like:
jasmine-es6 path
 
  1. "${workspaceRoot}/node_modules/jasmine-es6/bin/jasmine.js"
Running the above is the equivalent of running the command Jasmine-es6 in the command line. This will work, but in our case we want to be more specific and actually just run a specific spec file.
In a command line scenario I would run the following line:
Jasmine command line
 
jasmine-es6 "/tests/Tests1spec.js"
To add parameter in our configuration we need to use the specify the args array:
Args array
 
  1. "args": [
  2. "${workspaceFolder}\\tests\\Tests1spec.js"
  3. ]
If you use backslash instead than forward slash, you will have to escape them ( as shown above)

Conclusion

The above post is aimed at supporting you and hopefully save you some time. The debugging feature of Visual Studio Code are quite extensive ( I debugger PHP in the past and it worked perfectly).  Not that everything is set up, you can start debugging by clicking the green arrow in the debug page, or just by pressing F5 from your keyboard (make sure to add breakpoint where you would like the add to break).

There may be better method to debug, and most people would have webpack setup to support them in the traspilation and test run, but I wanted to go against current and try something different.

As always I am happy to receive any comment that can support the future readers.

I complete the post wit the complete file below:

Node Program debug in Visual Studio Code
 
  1. {
  2. // Use IntelliSense to learn about possible Node.js debug attributes.
  3. // Hover to view descriptions of existing attributes.
  4. // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  5. "version": "0.2.0",
  6. "configurations": [
  7. {
  8. "type": "node",
  9. "request": "launch",
  10. "name": "Launch Program",
  11. "program": "${workspaceRoot}/node_modules/Jasmine-es6/bin/jasmine.js",
  12. "args": [
  13. "${workspaceRoot}/tests/Test1spec.js"
  14. }
  15. ]
  16. }

 

Conference presentations – behind the scene

A few months ago, I was delighted to be part of the amazing DDDnorth conference that took place in Bradford. This time, I was actually facing the attendees as I was taking the role of speaker for the first time.

It was a truly amazing experience, and I want to share my afterthought with you all, in the hope that I will be able to convince some of you to take this extra step in your career.

The hidden Iceberg – The preparation

Many website accept your talk from the abstract ( a few hundred words to explain the content of your talk), and many speaker actually do not prepare the actual talk until their talk has been submitted. I thought that was just my mistake, but it seem to be a big mistake from newbie that I am not going to repeat again.

The actual preparation that goes behind a conference session is immense. I have spent almost 25 hours changing and adapting the Powerpoint and another 20+ repeating it over and over until I got it just right. It would have been fine if you share this over an extensive period of time, but do it between being approved and the actual talk ( less than a month) was not a great idea, and I really suggest you all to learn from my mistake!

I have been lucky to keep an initial copy of my presentation, and I have been able to compare it with the final one. It is admirable how much it changed. I am not just talking at the actual design of the slide or the odd pictures, but the overall content and message that the presentation broadcast to the audience.

This is probably one of the main reason why sometimes the abstract can be quite different from the actual presentation.

A journey to self discovery

Writing an abstract to submit a Call for paper (CFP), is quite easy. We all have our “special” topic that we like to discuss, or a personal experience that we want to share, and this is usually good enough to draft down the bare bones of a presentation. But the real work needed to actually create enough content to present a whole session is a different story.

Spending time, trying to put your thought on paper is not easy, I actually felt the pain of all writers, that have something beautiful stuck in their head, and do no know the best way to share it with others. Luckily I was surrounded by great people, I would ask you all to ask and get people involved, because there is nothing better to actually share your thoughts to give you the energy and the power to continue and make a great presentation.

When I applied to be a speaker, I actually thought to know enough on the topic, and did not think that I needed to do any research, but I was completely wrong. You can never know too much! I have learned so much on my specific topic, and the feedback from other speaker was completely the same! Some people have even confessed, that the main reason why they speak at conference or write blog post is to “force” themselves to actually research and study specific topics in details.

The main event

There are no nice words that I can share, or special powder that will save you from the “Speaking anxiety”. Some people are affected more than others, and luckily I coped very well with it.

If Anxiety does hit, I can only suggest to remember that it is too late to back now, so do you best, if thing goes wrong, just work hard and try again! We are all humans after all!!

In my case, I felt amazingly energetic after I started my session. For the first time I really felt like all the preparation, all the hard work and all the hours talking by myself were finally worth it! Having lots of people staring at you can be scary, but remember that people are not there to judge you, but they have joined your session because they think you and your topic are worth the time!

The actual talk and questions time will fly! You will not believe how quick it will be before someone will warn you of the time!

The after event will be the best part of the conference for you, it is the time to try and get as many feedback as possible, because do not forget that the aim is always getting better and improve, so even if you did something wrong, you just need to focus and see what you can do to improve and not focus too much on the actual mistake!

Conclusion

I have personally loved it, and I cannot wait to do it again. The amount of work that goes behind it is incredible, so make sure you are really ready for it, and give 150% of yourself, but do not let this get you down because the personal satisfaction is the feeling of accomplishment that you receive at the end cannot be explained!

 

 

Which Javascript framework should I learn first

This is probably one of the first question that comes into every mind of new developers. The framework world is cluttered with hundreds of Framework, all promising to be the best, the fastest and the easier to use, but which one is the most suitable for new starters.

In this post I am going to share my opinion on where to a new Javascript developer should start and give a small review of the most used frameworks.

What is a Javascript Framework

A JavaScript framework is an application framework written in JavaScript. It differs from a JavaScript library in its control flow:[1] a library offers functions to be called by its parent code, whereas a framework defines the entire application design.[2] A developer does not call a framework; instead it is the framework that will call and use the code in some particular way. Some JavaScript frameworks follow the model–view–controller paradigm designed to segregate a web application into orthogonal units to improve code quality and maintainability. Examples: AngularJS, Ember.js.Wikipedia

In a nutshell, Javascript framework will provide you a complete structure to support your development by forcing specific patterns and guidelines. Even if different framework support you in achieving the same result, the implementation differ quite considerably, and knowledge can not be transferred between them.

What are the best Javascript Framework

This paragraph is going to cover the most used framework available on the market right now. The framework are shared in “No particular order”.

Angular 4

Angular was one of the first frameworks to be pushed to the public bug in 2009. Due to its maturity and the large community, AngularJs is usually the first choice around new developers.

Angular has recently received a complete upgrade. The new version, due to be a complete rewrite, is not compatible with the old one. This means that many of the example that can be found around the internet, may not work. This problem will fade overtime, but now, it can obscure proper result.

Pros

  • Mature with 8 years of experience
  • Two way data binding
  • Highly testable
  • MVVC architecture

Cons

  • Complete rewrite of version 2, so old example may not work
  • “Scope” in angular can be tricky to learn at first
  • MVC could be hard to learn if not familiar with it

 

 ReactJs

I will start this paragraph by specify that for many people reactJs is not accepted to be a framework, as it does not fulfil the definition above. React ( if used by itself), is just a view engine. Due to its popularity, and the amount of available plugins I have inserted it in this list.

React has been created by the creator of Facebook and instagram, and has been firstly been released in 2013.

Even if younger than angular 2. React is catching up quite quickly.

Pros

  • Very efficient
  • Good with SEO, because Server side render is possible
  • very active community

Cons

  • It is only a view layer
  • It needs other components to fully work
  • Learning curve quite steep, due to its different approach in creating components.

MeteorJs

Meteor has been initially created in 2011, and like the other framework has a large active community. This framework offer full stack capacity covering all aspect required for a successful Web/Mobile App.

Pros

  • Easy to scale

Cons

  • It is designed to work with Mongo DB
  • Need good understanding of NodeJs

 

VueJs

Vue has been created in 2014 uses the MVVM design paradigm and offers two data binding. Vue is one of the youngest framework around, but it is gaining speed and growing it community.

Pros

  • Easy to understand
  • Good Documentation
  • Small in size

Cons

  • Offer too much flexibility
  • Most of the community is NON english speaker

My preferred framework

Now that we have defined the framework above, it is time to share, what are my personal opinion on this matter. I had the change to try a couple of the framework above. Both cases the learning curve has been quite steep to start, and it made me realise that most of my energy where used in learning the Framework requirement without using lots of Javascript.

In my case, this was not a problem as I have a strong JS knowledge, and therefore could focus on the framework requirement. But I personally think that all new developers should not really use any framework until they have fully embraced the basic javascript knowledge.

As I mentioned above, all the javascript framework available, uses slightly different structure and implementation, reducing your employability to a specific market share.

This may not seem a problem at the start when everyone is looking for the greatest and coolest, but things ca go wrong, and in a very short amount of time, and in that case having experience on a framework that is not in use anymore could be a problem.

Conclusion

It is essential to be comfortable with plain javascript first, before moving along and learn different framework.

Having the basic knowledge will be a great advantage when learning a new framework.

All framework have a specific segment of the market, and as such, deep research should be done before adopting one as the decision should be made by a project by project bases.

"