Forem: Alberto Fernandez Medina

Using Unity UI for in-game HUDs

Alberto Fernandez Medina — Wed, 14 Oct 2020 22:00:00 +0000

This article covers how to implement a basic U ser I nterface on Unity using Unity UI to display info to players.

Requirements

Basic knowledge of Unity
Complete “ Unity Physics 2D Using Collider2D and Kinematic Rigidbody2D ” or checkout the code from Genoma Invaders’ Github repository, branch tutorial/03

Intro

Last time we end up updating all the movement logic to be handled by Unity’s Physics engine and make use of its collision system to detect our player’s bullets colliding with the enemies to be destroyed.

This time we’ll be showing the Score Points on the game screen.

Unity’s UI

Unity has three types of “UI Toolkits” to display user interfaces:

UIElements : This is a new UI Toolkit in active development.
Unity UI : This is the most used UI Toolkit for Unity until now.
IMGUI : This is a UI Toolkit commonly used to display development UIs due to its simplicity and ease to use.

We will be using Unity UI for our game UI, starting with the score display.

To display our player’s score points, we will need to use the Text Visual Component. Let’s start by adding one to our Game Scene.

Canvas and Layout

As you can see, this will create 3 Game Objects in our Hierarchy Window, a Canvas containing Text, and something called EventSystem.

The Canvas serves to define an area that will render UI components. It has different render options to help place UI Components all over our game world (checkout the docs!). The Render Mode we will be using is the “Screen Space - Overlay” set by default.
The Text Object is the one in charge of display our text.
The EventSystem is a subsystem in charge of controlling the UI events and inputs. It handles navigation, input activation, and selection.

Select the Text Object and rename it to Score Text, then go to its Text Component and put some placeholder score in its Text input (like 1978) to have a reference of how it would look.

Now you may probably have noticed that there is no text shown in the Scene Window. This happens because the Canvas, as we said, is like a sticker in our camera, it is not part of the game world. To center our Game Window in the Canvas Game Object, select it in the Hierarchy Window and then, with the cursor over the Game Window, press F, this will move the Game Window view to fit the Game Object you have selected, in this case, the Canvas.

With the canvas on sigh now, it’s time to position the Score Text, select it, and in its Inspector Window under the Rect Transform section, click on the icon similar to a red reticle, this is the Anchor Presets selector. Now with the Anchor Presets selector opened when pressing Shift+Alt</kbd> you'll see that the selection icon change, select the one under the row with "top" label and the column with "right" label while pressing Shift+Alt</kbd>. This will place the Score Text Object on the top right corner of the Canvas and anchor it.

Note: You can read more about Rect Transform Component in Unity UI Documentation - Basic Layout section

If you now switch to Game Window should see something like this.

Unity UI Text Style

Now that our Text is positioned in the Canvas, let’s give it some styles and appearance similar to our game visuals.

First, we are going to change the font used for the text. We’ll be using Press Start 2P you can download it from codeman38’s webpage (the author). We placed the fonts under /Assets/Genoma Invaders/Fonts/Press Start P2/ to organize the project’s files.

To change the font for the Score Text Object:

Select it and change the Font Property under its Text Component.
Set its Font Size Property to 8 (this is the recommended size for this font),
Update the Alignment to the right and centered vertically.
Update the Color Property to be White (FFFFFF).

As a final tweak to adjust the size and position of the element, go to the Score Text Object’s Rect Transform Component and set the next properties:

Pos X: -8
Pos Y: -8
Pos Z: 0
Width: 64
Height: 8

Note: You should see the changes applied in the Game Window (remember to set the Taito 8080 resolution configured in the first lesson).

Updating Unity UI Text

The Score Text Object is ready to display our Game Score, and now we need some logic to update its Text value.

Create a new C# Script in the Project Window called Score.cs and place it under /Assets/Genoma Invaders/UI/ (new folder). We will use this Component to maintain the Score points for our Game.

Score.cs

using UnityEngine;
using UnityEngine.UI;

public class Score : MonoBehaviour
{
    private int score = 0;
    // https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/script-Text.html
    private Text text;

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.Awake.html
    private void Awake()
    {
        text = GetComponent<Text>();
    }

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.Start.html
    private void Start()
    {
        text.text = score.ToString();
    }

    public void AddScore (int points)
    {
        score += points;

        text.text = score.ToString();
    }
}

The previous code does set the Text value to the initial score (0) whenever the Game Starts and update it when someone calls the method AddScore. Attach it to the Score Text Object and Play the Game, you should see the Score Points to 0.

With this new Component attached to the Text Score Object, we can use the Score.AddScore method to increment our Game Score. Let’s update the Enemy.cs to communicate with the Score Component inside the Score Text Object. We need to find and store a reference to the Score Component to call its AddScore method whenever the player kills an Enemy.

Enemy.cs

// ...
public class Enemy : MonoBehaviour
{
    // ...

    private Score score;

    private void Awake()
    {
        // ...

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Object.FindObjectOfType.html
        score = FindObjectOfType<Score>();
    }

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.OnDestroy.html
    private void OnDestroy()
    {
        score.AddScore(100); // Increment game score by 100
    }
}

This way, whenever Destroy method is called (remember that the Bullet Component is calling this method over the Enemy Object) with a Game Object containing an Enemy Component, it will update the Score points before being destroyed from the Scene.

Let’s try it

Conclusion

We ended up with a game displaying a score text that updates whenever an enemy is killed and learning a bit about Unity UI systems.

You can get the code generated by following this tutorial in Genoma Invaders’ Github repository, branch tutorial/04.

Happy Game Dev! 👾

Unity Physics 2D Using Collider2D and Kinematic Rigidbody2D

Alberto Fernandez Medina — Tue, 25 Aug 2020 22:00:00 +0000

Learn how to handle 2D game objects collisions while making a space invaders 2D game using the Unity physics 2D engine with 2D colliders and kinematic 2D rigid bodies.

Requirements

Unity 2020.1
Visual Studio Editor
Complete “ How to Move 2D Objects in Unity ” or checkout the code from Genoma Invaders’ Github repository, branch tutorial/02

Intro

In the last tutorial, we walked through How to Move 2D Objects in Unity using the Unity’s Scripting API, ending up with a Scene containing a Player Game Object that moves when pressing directional input buttons and shooting bullets that move upwards in a consistent manner when a Fire1 related input is pressed.

Our next steps will be to:

Make Bullets collide with the Enemies
Organize our code

Until now, the Game Objects of our game were moving by updating its Transform.position values by calling Transform.Translate method. But, to let Unity detect collisions between objects, this is a bad practice, we need to change this approach to make use of Unity’s Physics 2D engine so that it can notify us about collisions between Game Objects.

Unity’s Kinematic Rigidbody2D, Moving Objects with Physics

To move a Game Object using Unity’s 2D Physics we need to add Rigidbody2D Component to it and call Rigidbody2D.MovePosition to move it, this way the Physics2D engine can handle the movement and take care of the physics calculations implied on it.

Player Movement with Physics

Let’s start with the Player Game Object by adding the Rigidbody2D Component to it.

Now there is a small point in adding physics to game objects in Unity. If you play the game, you will see how our Player Game Object now falls into the abyss.

“Goodbye dear friend!”

The Player Game Object is falling because Unity’s 2D Physics engine is now applying gravity to the Player Game Object. The thing is, we don’t want gravity in this game. We want them to move whenever we want them to move. We are only going to use Unity’s 2D Physics engine for collision detection. To achieve this, we need to switch the Rigidbody2D.bodyType property.

Using the Unity Inspector window, change the Player’s Rigidbody2D Body Type property to Kinematic.

Note: Now if you play the game will see that the Player stay still.

Kinematic Rigidbodies will ignore all forces and collision applied to them, so it will stay still unless moved by scripting. One thing more to do with the Rigidbody2D properties is to check “ Use Full Kinematics Contacts ” checkbox to tell the Unity’s 2D Physics engine that this object can collide with other kinematic objects.

Note: Checkout Unity’s Manual section “Rigidbody 2D” to have more context about this topic.

There, our Player is now in position. It’s time to update Player’s Component code to use RigidBody2D instead of Transform to move the Player Game Object.

First, we need the Player Component to depends on Rigidbody2D Component.

Player.cs

using UnityEngine;

// https://docs.unity3d.com/2020.1/Documentation/ScriptReference/RequireComponent.html
[RequireComponent(typeof(Rigidbody2D))]
public class Player : MonoBehaviour
{
    // ...
}

Note: Some code has been hidden under // ... to show only relevant code.

By using the RequireComponent Attribute, whenever a Player Component is added to a Game Object, if there is not Rigidbody2D Component attached, it will be added.

Now we need the Player Component to store a reference to the RigidBody2D Component to communicate with it.

Player.cs

// ...
public class Player : MonoBehaviour
{
    [SerializeField]
    private float speed = 2;

    [SerializeField]
    private GameObject bullet;

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Rigidbody2D.html
    private Rigidbody2D rb2D;

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.Awake.html
    private void Awake()
    {
        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Component.GetComponent.html
        rb2D = GetComponent<Rigidbody2D>();
    }

    private void Update()
    {
        // ...
    }
}

We have added a new method to our Player Component called Awake, and inside we are using GetComponent method to obtain a reference to the attached Rigidbody2D. Awake method serves to hook any logic needed for our Component when the game starts a Scene or when a Game Object containing this Component is instantiated. It is usually used to setup references like we did for the Rigidbody2D Component.

Note: To get more info about this topic checkout Unity’s Manual section about “Order of Execution for Event Functions”.

Now that our Player Component has the reference to Rigidbody2D stored, we can focus on the logic to move the Game Object.

Player.cs

     // ...

     // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Rigidbody2D.html
     private Rigidbody2D rb2D;
+    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Vector3-zero.html
+    private Vector3 move = Vector3.zero;

     private void Awake()
     {
         // ...
     }

     private void Update()
     {
         // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Input.GetAxisRaw.html
         float rawHorizontalAxis = Input.GetAxisRaw("Horizontal");

-        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Vector3-zero.html
-        Vector3 direction = Vector3.zero;
-        direction.x = rawHorizontalAxis;
-
-        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Time-deltaTime.html
-        float timeSinceLastFrame = Time.deltaTime;
-
-        Vector3 translation = direction * speed * timeSinceLastFrame;
-
-        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Transform.Translate.html
-        transform.Translate(
-          translation
-        );
+        move.x = rawHorizontalAxis;

         // ...
     }

+    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.FixedUpdate.html
+    private void FixedUpdate()
+    {
+        if (move != Vector3.zero)
+        {
+            // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Time-fixedDeltaTime.html
+            Vector3 translation = move * speed * Time.fixedDeltaTime;
+            Vector3 newPosition = transform.position + translation;
+
+            // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Rigidbody2D.MovePosition.html
+            rb2D.MovePosition(newPosition);
+        }
+    }
 }

Note: The syntax shown here is in diff unified format to show replaced code. Due to syntax highlighter limitations, C# syntax colors are disabled.

Let’s explain the changes. We have removed all related old movement logic except the logic in charge of checking for movement input with Input.GetAxisRaw, added a new private property to Player class called move of type Vector3 with a default value of Vector3.zero, then we are updating the property move.x value in Player’s Update method with the value retrieved from the horizontal axis input. We had defined a new method FixedUpdate to handle physics-related logic. In here, if move property value differs from Vector3.zero, it will calculate the Game Object translation based on the move and the speed values multiplying it by the time passed (in this case Time.fixedDeltaTime). This computed translation is added to the current position. Then we call Rigidbody2D.MovePosition method to move the Game Object. This way, the Player Game Object is moved by the Rigidbody2D Component and taken into account b the physics engine.

If you play the game, there should be no difference in the movement or any noticeable changes. The difference here is that the physics engine works behind the curtains paying attention to each movement of our Player Game Object.

Bullet Movement with Physics

Now that we have done this with the Player, let’s do it with its Bullets.

Go to your Project window in the Unity editor and attach a Rigidbody2D Component to Bullet Game Object Prefab. Remember to set it to Kinematic and to check the “Use Full Kinematics Contacts” checkbox. After this, you should play the game. If everything is configured correctly, the bullets should move straight up when shooting.

Edit Bullet.cs code and add the RequireComponent attribute to require Rigidbody2D.

Bullet.cs

using UnityEngine;

// https://docs.unity3d.com/2020.1/Documentation/ScriptReference/RequireComponent.html
[RequireComponent(typeof(Rigidbody2D))]
public class Bullet : MonoBehaviour
{
    // ...
}

Add the logic in Bullet.cs to store the reference to the RigidBody2D Component.

Bullet.cs

// ...
public class Bullet : MonoBehaviour
{
    // ...

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Rigidbody2D.html
    private Rigidbody2D rb2D;

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.Awake.html
    private void Awake () {
        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Component.GetComponent.html
        rb2D = GetComponent<Rigidbody2D>();
    }

    // ...
}

And finally, update its logic to move using the physics engine.

Bullet.cs

// ...
 public class Bullet : MonoBehaviour
 {
     // ...

     // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Rigidbody2D.html
     private Rigidbody2D rb2D;
+    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Vector3-up.html
+    private Vector3 move = Vector3.up;

     private void Awake()
     {
         // ...
     }

-    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.Update.html
-    private void Update()
-    {
-        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Vector3-up.html
-        Vector3 direction = Vector3.up;
-
-        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Time-deltaTime.html
-        float timeSinceLastFrame = Time.deltaTime;
-
-        Vector3 translation = direction * speed * timeSinceLastFrame;
-
-        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Transform.Translate.html
-        transform.Translate(
-          translation
-        );
-    }
+    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.FixedUpdate.html
+    private void FixedUpdate()
+    {
+        if (move != Vector3.zero)
+        {
+            // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Time-fixedDeltaTime.html
+            Vector3 translation = move * speed * Time.fixedDeltaTime;
+            Vector3 newPosition = transform.position + translation;
+
+            // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Rigidbody2D.MovePosition.html
+            rb2D.MovePosition(newPosition);
+        }
+    }
 }

Notice that the Update method has been removed since it is no longer needed, and we are using the same code as with the Player Component for the FixedUpdated method.

No changes should be noticed when playing the game (physics engine working).

Enemies with physics

Last but not least, update the Enemies Game Objects to have a Rigidbody2D of type Kinematic and “Use Full Kinematics Contacts” checkbox checked.

And update its Enemy.cs Component code to require and store the reference of Rigidbody2D.

Enemy.cs

using UnityEngine;

[RequireComponent(typeof(Rigidbody2D))]
public class Enemy : MonoBehaviour
{
    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Rigidbody2D.html
    private Rigidbody2D rb2D;

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.Awake.html
    private void Awake()
    {
        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Component.GetComponent.html
        rb2D = GetComponent<Rigidbody2D>();
    }
}

This one was the hardest. We are not going to implement any movement logic yet on the Enemy.

Yay! We have finished providing our Game Objects with physic properties and movement. Play the game to ensure everything moves correctly, and nothing falls into the void. It’s time to make things clash.

Unity’s Collider2D, Detecting Collisions

Now that Game Objects has physical body representation, the physics engine needs a way to detects collisions between these bodies. This can be made using 2D Colliders. There are several types of Collider2D based in their shape, we will use Box Collider 2D Component given its simplicity and that we do not need complicated shapes yet for the project.

To make a collision possible, we need 2 Game Objects with Colliders2D attached to them to communicate collisions between them. We are going to make our Bullets collide with Enemies Game Objects.

Bullet to Enemy Collision

Start with the Bullet Game Object Prefab. Open the Bullet Prefab on the Editor by making double click on it.

Add the Box Collider 2D Component, check “Is Trigger” box, this will set the collider to act as a trigger making the physics engine notify the collisions rather than simulate them. Set the Size property to X = 0.125 and Y = 0.25 units. This size makes the Collider area equal in size to the Sprite, the Bullet Sprite have a size of 2x4 pixels, that translated to game units (1 unit -> 16 pixels) is equal to 2 / 16 = 0.125 and 4 /16 = 0.25.

Do the same for both Enemy Game Objects in the Game Scene, this time the Size is X = 0.5 and Y = 0.5625 (8x9 pixels), and we will need to set Offset property Y = 0.03125 (this moves the collider 0.5 pixels up to center it with the sprite).

You can copy Components with its property values to other Game Object using the Inspector Window. Click on the “3 dots button” at the top left corner of the Enemy’s Box Collider 2D Component, select “Copy Component”, then select the other Enemy Game Object and click on the “3 dots button” at the top left corner of its Transform Component, select “Paste Component As New”. This will attach a new Box Collider 2D Component to the Game Object with the same property values.

Now that we have two kinds of Game Objects (Bullets and Enemies) with physical bodies and collision detection, we can handle collisions between them. If you play the game, there shouldn’t be any relevant changes (nothing falls and bullets still pass through).

Coding time! Edit the Bullet Component script. We are going to add a new method called OnTriggerEnter2D. This method is called whenever a collision is detected by any Collider2D attached to the Game Object with property “Is Trigger” enabled. It will be called when our Bullet Game Objects collide with the Enemy’s Collider2D.

Bullet.cs

// ...
public class Bullet : MonoBehaviour
{
    // ...

    // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/MonoBehaviour.OnTriggerEnter2D.html
    private void OnTriggerEnter2D(Collider2D collider2D)
    {
        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Component.CompareTag.html
        if (collider2D.CompareTag("Enemy"))
        {
            //https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Object.Destroy.html
            Destroy(collider2D.gameObject);
        }
    }
}

The Bullet Component is now detecting collisions. To avoid it from destroying every Collider2D it collides with, we have added a condition to check if the Game Object it collides with has the Tag “Enemy” and destroying it if so. But wait, if you play the game still nothing happens, we need to tag our Enemy Game Objects with the “Enemy” tag.

Unity Tags for Collider Filtering

To set a Tag in our Enemy Game Object, select the Enemy in the Editor and go to the Inspector Window, the Tag select input is placed in the upper part of the Inspector Window. We need to add a new one, to add a new Tag click on the Tag input, and select the “Add Tag…” option, then add the “Enemy” Tag.

Now select both Enemy Game Objects and add to them the “Enemy” Tag. If you play the game, you can now kill enemies. Pew! Pew!.

Conclusion

We have covered a lot in this post:

Represent Game Objects in Unity as physic bodies to be handled and moved by its 2D Physics engine
Detect collisions between Game Objects and apply some logic to it
Manage Tags in a Unity Project and tag Game Objects to be filtered during collision detection logics

You can get the code generated by following this tutorial in Genoma Invaders’ Github repository, branch tutorial/03.

Remember to dig into documentation sites to have more context on what does what:

Happy Game Dev! 👾

Getting Started in Unity 2D Game Development

Alberto Fernandez Medina — Sun, 02 Aug 2020 16:28:53 +0000

This tutorial covers some basic concepts about start developing 2D games in Unity. Game Object, Components, Sprites, how to handle Pixel Art for games in Unity, and helps to get used to Unity editor interface.

Requirements

To follow this Unity tutorial, you will need to:

Genoma Invaders Game

The game we will be developing during this tutorial series is Genoma Invaders.

Genoma Invaders is a Fixed shooter from the Shoot 'em up game genre where you are a microscopic submarine killing bacteria, virus, and other microorganisms inside a human body.

To define this project and its scope, a very simple Game Design Document has been created.

Note: Don't use this project as an example for game design as there is not much design process behind this project due to its educational purpose

Project File Structure

It is not mandatory, but a way to keep things tidy is to create a new directory inside /Assets with the name of your game, in this case, /Assets/Genoma Invaders, and move the Scenes directory inside of it. This way, all the game-related assets are contained inside this directory so they do not get mixed with 3rd party assets or plugins.

Building the First Game Scene

Let's start with the Scene Unity creates whenever you create a new project by renaming it from SampleScene to Game. Here is where all the game action will happen.

Every game in Unity is contained within one or multiple scenes. For this project, we will be using them to store one level in each one and the main menu in another one, but for now, we only need one to start our game development.

Game Objects

The next item smaller than a Unity scene is a Game Object. They comprehend the bricks to build a game, graphics, sounds, and logic. A Game Object can represent multiple things in a Unity game, players, enemies, lights, the ground, trees, cameras. These objects can also represent things that the player can not see, like the camera itself or an object in charge of reviving the player whenever it dies.

Unity starts a project always by placing a Camera Game Object inside the Scene (depending on the project template it could put more stuff). A Camera is essential since it represents the player's eyes as they will see what the camera sees. Do not mind it too much since we will not be handling it yet.

A Game Object will represent the player. To create Game Objects in the Scene, click on the menu GameObject > 2D Object > Sprite.

It will create a new Game Object in the Scene called New Sprite. Rename it to Player and ensure its position is in X=0 Y=0 Z=0 in the Inspector window.

Components

This Game Object we renamed Player should show a Sprite Renderer in the Inspector window.

Each section in the Inspector window, divided by a line and a header, represents a Component which is the next piece smaller than a Game Object. Game Objects contains Components that provide different features to the Game Object, the most common Component you can find in a Game Object is the Transform Component. It gives the Game Object the ability to be positioned, rotated, or scaled inside the Scene, so if the Game Object renders something, it will be placed based on that values or could calculate its distance against other entities in the Scene.

Sprites

Time to inject some graphics into the game. Take this Player sprite:

And put it into the project. You can do it by dragging it into the Project window or placing it with your operating system file explorer into the project Assets directory. Place it under Assets/Genoma Invaders/Player/Player.png.

Let assign the Player sprite to the Player Game Object in the Scene:

Select the Player in the Scene Hierarchy window
In the Inspector window, on the Sprite Renderer component, click on the circle of the left to the Sprite field to open the Select Sprite window
Select the Player sprite on the Select Sprite window

Now the Player entity is visible within the game Camera. To check this, go to the Game view view, you should see something like this:

That little dot is our Player rendered by the camera. The reason it is so small is that the size of the sprite is 16x16 pixels. Sprites, Cameras, and settings in Unity need to be configured to render Pixel Art correctly.

Pixel Art in Unity

To render pixel art correctly in Unity, we need to make a few changes.

Unity Texture 2D Import Settings for Pixel Art

The primary problem Unity has with Pixel Art is that it treats the images used for the Game Objects as Textures, and it applies some optimization over them to improve load and render times. The problem is that that optimization is useful only if we are working with large resolution images that need to be compressed or optimized. In the case of Pixel Art, these optimizations are not required since these graphics are so small in size.

To configure Player Sprite with proper settings, select it on the Project window to display its settings on the Inspector window.

Pixels Per Unit: 16 (It will make the sprite bigger in the Scene because when applying this value, it means that for this sprite 16 pixels will have to be rendered inside 1 game world unit)
Filter Mode: Point (no filter) (Will prevent blurriness with the pixels since that option is in charge of filtering the texture when it gets stretched)
Compression: None (This prevents Unity from compressing the image that also will cause blurriness)

Press the Apply button to save the changes.

Note: This process needs to be made with every sprite included in the project.

If you look now in the Game view, the Player Sprite should look bigger.

2D Pixel Perfect Package

Another tweak we can do to help the Unity project render pixel graphics is to install the 2D Pixel Perfect package.

2D Pixel Perfect Package Installation

If you created the project selecting the 2D Project Template in Unity Hub you already have this package installed.

To install the package, open the Package Manager window.

Set Packages option to show All packages.

Select the 2D Pixel Perfect package and the press the Install button.

2D Pixel Perfect Package's Pixel Camera

The 2D Pixel Perfect package comes with a Component called Pixel Camera. Unity Cameras are not prepared to render pixel graphics correctly, and this Component provides Unity's Cameras with behavior to handle pixel viewport logics and other features to help your game look more pixelated.

Select the Main Camera in the Hierarchy window to show its Inspector window. To add the Pixel Camera Component to the Main Camera, click on the Add Component button. Go to Rendering and then select Pixel Perfect Camera (you can also find it using the search input).

Once the Main Camera has the Pixel Perfect Camera Component, edit its parameters.

Assets Pixels Per Unit: 16 (the same value we used for the Player Sprite)
Reference Resolution: 224x256 (you'll know why these values later)
Upscale Render Texture: checked
Crop Frame: X and Y checked

Note: checkout 2D Pixel Perfect package documentation for more info.

Arcade Cabinet Taito 8080

Space Invaders were played in an arcade cabinet with a Taito 8080 motherboard which could render a resolution of 224x256 pixels.

Unity can simulate resolutions and aspect ratios freely. Let's begin by setting up a new Aspect configuration on the Game view:

To simulate a Taito arcade machine create a mew aspect with 224 with and 256 height:

When the new aspect is selected, the Game view will change to represent this resolution. To try how the game looks under this resolution, press the Play button and select it.

Stop the game by pressing the Play button again.

Enemies

Let's make the same process with this Enemy sprite:

Place it under /Assets/Genoma Invaders/Enemy/Enemy.png and update its settings as we did with the Player sprite.

Pixels Per Unit: 16
Filter Mode: Point (no filter)
Compression: None

Now, to create the Enemy Game Object in the Scene, there is another way to create it. Drag and drop the Enemy Sprite from the Project window to the Hierarchy window, this will create a new Game Object with a Sprite Renderer Component called "Enemy" in the Scene.

Now that we have two visible game objects in the Scene let's place them where they suppose to be in the game. Move the Player and the Enemy to be positioned similar to this.

Now select the Enemy Game Object and press Ctrl/Cmd + D, in the Hierarchy should appear an Enemy (1) Game Object, you have just duplicated a Game Object, place it next to its partner, and you should end with something that starts to smell like a game.

Wrap Up

We have seen:

How to import Sprites in a Unity project
How to create Game Objects in Unity
How to add components to a Game Object in Unity
How to adapt a Unity project, its camera, and sprites to be Pixel Art friendly

This is all for now.

The resulting work of this tutorial can be checked out in the Genoma Invaders Github, branch tutorial/01.

Happy Game Dev! 👾

How to Move 2D Objects in Unity

Alberto Fernandez Medina — Fri, 31 Jul 2020 22:00:00 +0000

This tutorial shows basics for Unity 2D Game Development concepts like adding custom components to Game Object, fundamental Unity scripting with C#, 2D Game Object movement in Unity, how to handle inputs in Unity, and how to instantiate Game Object in Unity.

Disclaimer

Due to this course's intention, we will not cover basic knowledge in programming with C# in Unity but rather provide info with complex terms in this language or Unity Scripting API.

To get more info and learn about these topics, you can refer to:

Requirements

Complete "Getting Started in Unity 2D Game Development" or checkout the code from Genoma Invaders' Github repository, branch tutorial/01
Have basics knowledge in programming with C#
Visual Studio Editor (you should have installed it when installing Unity) or another code editor of your preference

In the previous tutorial, "Getting Started in Unity 2D Game Development", we walk through basic concepts about developing 2D games in Unity, ending up with a scene with some still Game Objects. It’s time to give them some movement logic starting by the Player.

This time we will learn to move 2D Object in Unity by scripting in C# using Game Components.

Custom Components

To move our Player, we will need to add some logic to its dumb Game Object. We will do it by creating a Custom Component containing C# code and adding it to the Player Game Object.

Select the Player Game Object and press the “Add Component” button in the Inspector window. Then, write in the search input Player, select New Script, and press the “Create and Add” button.

Note: checkout Unity’s Manual section “Creating components with scripting” for more info.

This action will create a C# file under /Assets/Player.cs that defines a component named “Player”, and then it will add this Component to the Player Game Object. Move the Player.cs file to /Assets/Genoma Invaders/Player/ directory using the Project window to maintain the project’s files organized.

Player Controller

The Player component will be the Player Controller or, in other words, the Component in charge of handle the player’s logic.

If you open the file you’ll see this:

Player.cs

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

public class Player : MonoBehaviour
{
    // Start is called before the first frame update
    void Start()
    {

    }

    // Update is called once per frame
    void Update()
    {

    }
}

That is the basic code structure Unity Editor creates for every script/component created in the project.

Now we are going to make de same, and create an Enemy Custom Component for the Enemy Game Objects. This time we are using a different technique. On the Project window, go to /Assets/Genoma Games/Enemy right click on it to open the contextual menu and select Create > C# Script, then name the file Enemy.

When Enemy.cs file is created, Unity reloads for a sort time and will register a new component to be added to Game Object named Enemy. Go ahead and add it to both Enemy Game Objects.

Note: Remember to add the Enemy component to both enemies.

Game Object Movement

To make the Player Game Object move, edit Player.cs file. First, we will clean it up a bit, so it doesn’t have unnecessary code:

Player.cs

using UnityEngine;

public class Player : MonoBehaviour
{
    private void Update()
    {
    }
}

Now, we will add some logic into its Player Controller’s Update loop method.

Player.cs

using UnityEngine;

public class Player : MonoBehaviour
{
    private void Update()
    {
        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Vector3-right.html
        Vector3 right = Vector3.right;

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Time-deltaTime.html
        float timeSinceLastFrame = Time.deltaTime;

        Vector3 translation = right * timeSinceLastFrame;

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Transform.Translate.html
        transform.Translate(
          translation
        );
    }
}

Note: Visit any of the links in the code’s comments for more info.

This code is creating a Vector3 pointing to the right (1, 0, 0) and multiplying it by time elapsed since the last frame, and then calls Transform.Translate method with the resulting Vector3 which will move the Game Object that distance.

TL;DR; This will make the player move 1 Scene unit per second to the right.

To see the result go to Unity Editor and press the “Play” button (You can use the keyboard shortcut Ctrl/Cmd+P).

It’s alive!!! But we need to be able to control this little guy.

Detect Player Input

To control the Player, we need to use Unity’s Input Manager. With the Input.GetAxisRaw method, you can retrieve the corresponding axis input value, in this case, if some left or right key is pressed.

Player.cs

using UnityEngine;

public class Player : MonoBehaviour
{
    private void Update()
    {
        // https://docs.unity3d.com/ScriptReference/Input.GetAxisRaw.html
        float rawHorizontalAxis = Input.GetAxisRaw("Horizontal");

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Vector3-zero.html
        Vector3 direction = Vector3.zero;
        direction.x = rawHorizontalAxis;

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Time-deltaTime.html
        float timeSinceLastFrame = Time.deltaTime;

        Vector3 translation = direction * timeSinceLastFrame;

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Transform.Translate.html
        transform.Translate(
          translation
        );
    }
}

Now you can control the player.

The problem is, it is a bit slow. To fix this, we are going to add one more value to our player logic. Edit the Player component code, add a speed property to it, and include this value in the translation calculus.

Player.cs

using UnityEngine;

public class Player : MonoBehaviour
{
    private float speed = 2;

    private void Update()
    {
        // ...

        Vector3 translation = direction * speed * timeSinceLastFrame;

        // ...
    }
}

Note: Some code has been hidden under // ... to show only applied changed.

Now the Player should move twice as fast if you try it. But there is one small problem here if we want to change our Player speed value we need to open its code and edit the value and then wait for Unity to recompile. Unity provides various ways to allow the exposure of properties in the editor so you can tweak as many values as you want without editing any code. You could set the property to be public (which I don’t recommend to enforce code cleanliness), or you could add the SerializeField attribute to the Player’s speed property, we will do the second.

Player.cs

using UnityEngine;

public class Player : MonoBehaviour
{
    [SerializeField]
    private float speed = 2;

    // ...
}

Now, if you go to the Unity Editor and checkout the Player Component at the Inspector window, you’ll see that now the Component has a new input called Speed.

Now the 2 we set for the speed property will be a default value when the Component is added to a Game Object, and the final used value for the logic will be the one set at the editor. You can edit it even while playing to adjust it to your preferred value.

Note: Properties changed during Play mode will not be saved and will reset to its value before stating Play mode. More info in Unity’s Manual section “Game View“

Instantiate Game Objects

Time to make our Player shoot some bullets. Download this Bullet sprite:

And place it under /Assets/Bullet/ (new directory). Remember to edit the Sprite settings as we did with the Player and Enemy sprites in the previous tutorial. Then use it to create a new Game Object in the Scene called Bullet.

This Bullet Game Object will need custom logic to move and do stuff, so let’s create a new C# Script called Bullet and add its Component to the Bullet Game Object. Edit the file.

Bullet.cs

using UnityEngine;

public class Bullet : MonoBehaviour
{
    [SerializeField]
    private float speed = 5;

    private void Update()
    {
        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Vector3-up.html
        Vector3 direction = Vector3.up;

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Time-deltaTime.html
        float timeSinceLastFrame = Time.deltaTime;

        Vector3 translation = direction * speed * timeSinceLastFrame;

        // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Transform.Translate.html
        transform.Translate(
          translation
        );
    }
}

We have added similar logic to our Bullet Game Object as we did to the player, but this time it only moves upwards and with a higher speed.

The problem now is that we only have one Bullet, and it appears and starts moving whenever we start playing. We need it only to appear when we are pressing the fire button. To achieve this, we will need to create a Prefab from our Bullet Game Object.

To create a Unity Prefab from an already existing Game Object, you need to drag and drop it to the Project window.

A Prefab is like a blueprint of a Game Object. It allows us to create multiple copies of the same Game Object without having them in the Scene. If you take a look at the Hierarchy window, you will see that the Bullet Game Object now has a different color, icon, and a little arrow to the right, this is the way Unity indicates if a Game Object in the Scene is related with a Prefab. Delete this Game Object from the Scene.

Check the Bullet Prefab properties within the Inspector window and ensure that it has Transform.position to x=0 y=0 z=0 and Bullet speed=0. We need to update the Player’s logic to instantiate this Game Object whenever we press the “Fire1” button (which is mapped to left ctrl, mouse 0 and joystick button 0).

Note: Checkout Unity’s Manual section “Input Manager” to know more on how to configure input mappings.

Player.cs

using UnityEngine;

public class Player : MonoBehaviour
{
    // ...

    [SerializeField]
    private GameObject bullet;

    private void Update()
    {
        // ...

        // https://docs.unity3d.com/ScriptReference/Input.GetButtonDown.html
        if (Input.GetButtonDown("Fire1"))
        {
            Vector3 playerPosition = transform.position;

            // https://docs.unity3d.com/2020.1/Documentation/ScriptReference/Quaternion-identity.html
            Instantiate(bullet, playerPosition, Quaternion.identity);
        }
    }
}

Note: Some code has been hidden under // ... to show only applied changed.

We have defined a new Player Component property called bullet that will store the reference to the Bullet Prefab Game Object. Then we have updated the Update with more code to check if any input mapped to the button “Fire1” has been pressed down during this frame, if it has, then the script will instantiate a new Bullet Game Object in the Scene at the Player’s position (with no rotation). Select the Player Game Object in the Scene and update its properties in the Inspector window dragging the Bullet prefab to its Bullet property in the Player Component.

Now you are ready to fire!!!

Conclusion

Summing Up we have:

Add a new custom Player Component made with C# to our Player Game Object
Implement moving mechanics to the Player and Bullet Game Objects
Handle Player Inputs to move and shoot Bullets

You can get the code generated by following this tutorial in Genoma Invaders Github repository, branch tutorial/02.

Remember to dig into documentation sites to have more context on what does what:

Happy Game Dev! 👾

How To Install Unity 2020.1

Alberto Fernandez Medina — Wed, 01 Jul 2020 22:00:00 +0000

In this article, you will learn how to install Unity 2020.1.0b13 (Beta) using UnityHub 2.3.2 to start developing games.

UPDATE: Unity 2020.1 is no longer in beta but you can still use this guide for stable releases

Requirements

To install Unity, you will need first to install UnityHub.

Unity Installation

Now to install Unity start UnityHub and go to Installs section and then click on the ADD button.

Then select the Unity version you would like to install, in this case Unity 2020.1.0b13 (Beta) and click NEXT.

Check the box of Microsoft Visual Studio Community 2019 to install it as it will be the IDE you will be using for coding.

You will have to agree to Microsoft Visual Studio Community 2019 License terms.

After that, you will see a box with a loading bar meaning that the installation of Unity and Visual Studio is in progress.

Once the installation completes, you will be ready to open or start a new project with Unity 2020.

Checkout Unity 2020.1 Manual "Installing Unity" Chapter for more info

Happy Game Dev! 👾

Continuous Integration for Express APIs with Travis CI

Alberto Fernandez Medina — Wed, 20 Dec 2017 10:48:36 +0000

This article covers how to use Travis CI service with NodeJS for an open source project hosted on GitHub. At the end, you would be able to setup a basic build pipeline to automatically validate your code using Continuous Integration (CI).

Note: This is the 6th post of a series about Building APIs With Express. The code of this post will be developed over the generated code of the last post (Testing an API Against Documentation).

Travis CI

Travis CI is one of the most used Continuous Integration services in the open source community. It's ridiculous how easy is to enable it for a GitHub project. To activate it first I need to have an account in travis-ci.org and give it access to GitHub projects, then in the Travis CI profile page activate the service for the project.

And that's all I need, thanks for the reading! Ah... ok, maybe there is needed something more...

Ok, to start building things with Travis I have to update the code. Once Travis detects some new branch or commits on the repo it will run a build with that code , but at this point, it will fail.

Setup Travis CI for NodeJS

Yes, there is a little thing to do before Travis starts working smoothly. It doesn't know what to do with that GitHub repository, to help in this, the repo has to have a config file (.travis.yml) that tells Travis what to do with the code. If it doesn't find this file it will try to build the project using Ruby.

`.travis.yml`

language: node_js # Sets which engine use to build the project  
node_js: "node" # Specifies node version to use "node"="latest"

This is the simplest Travis CI config file for start building in NodeJS.

Note: More info about the configs on the docs for Travis with JavaScript.

First build

After committing this file and uploading it to GitHub, Travis will start a new build, in this case with the next logs:

Worker information  
hostname: b4baa4ff-edbd-48aa-b09f-bc84b287b798@1.i-0a50124-production-2-worker-org-ec2.travisci.net  
version: v3.4.0 https://github.com/travis-ci/worker/tree/ce0440bc30c289a49a9b0c21e4e1e6f7d7825101  
instance: 7917cbf travisci/ci-garnet:packer-1503972846 (via amqp)  
startup: 571.280161ms  
Build system information  
Build language: node_js

...

MongoDB version  
MongoDB 3.2.16

...

$ git clone --depth=50 --branch=post/06 https://github.com/AlbertoFdzM/another-todo-api.git AlbertoFdzM/another-todo-api
Cloning into 'AlbertoFdzM/another-todo-api'...  
remote: Counting objects: 124, done.  
remote: Compressing objects: 100% (2/2), done.  
remote: Total 124 (delta 0), reused 2 (delta 0), pack-reused 121  
Receiving objects: 100% (124/124), 79.47 KiB | 15.89 MiB/s, done.  
Resolving deltas: 100% (54/54), done.

$ cd AlbertoFdzM/another-todo-api
$ git checkout -qf dac5b5b13eef6d36ec76538c8194ce32923d628a
$ export PATH=./node_modules/.bin:$PATH
Updating nvm  
$ nvm install node
Downloading and installing node v9.1.0...  
Downloading https://nodejs.org/dist/v9.1.0/node-v9.1.0-linux-x64.tar.xz...  
######################################################################## 100.0%
Computing checksum with sha256sum  
Checksums matched!  
Now using node v9.1.0 (npm v5.5.1)

$ node --version
v9.1.0  
$ npm --version
5.5.1  
$ nvm --version
0.33.6  
$ yarn
yarn install v0.27.5  
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
Done in 131.09s.

$ npm test

> another-todo-api@0.0.0 test /home/travis/build/AlbertoFdzM/another-todo-api
> dredd

info: Configuration './dredd.yml' found, ignoring other arguments.  
warn: Apiary API Key or API Project Subdomain were not provided. Configure Dredd to be able to save test reports alongside your Apiary API project: https://dredd.readthedocs.io/en/latest/how-to-guides/#using-apiary-reporter-and-apiary-tests  
info: Starting backend server process with command: npm start  
info: Waiting 3 seconds for backend server process to start

> another-todo-api@0.0.0 start /home/travis/build/AlbertoFdzM/another-todo-api
> set DEBUG=another-todo:* && node bin/www

(node:4653) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): MongoError: failed to connect to server [localhost:27017] on first connect [MongoError: connect ECONNREFUSED 127.0.0.1:27017]
info: Beginning Dredd testing...  
info: Found Hookfiles: 0=/home/travis/build/AlbertoFdzM/another-todo-api/docs/hooks.js  
error: GET (200) /tasks duration: 120101ms  
error: Error connecting to server under test!  
GET /v1/tasks - - ms - -  
error: POST (201) /tasks duration: 120105ms  
error: Error connecting to server under test!  
error: GET (200) /tasks/586e88337106b038d820a54f duration: NaNms  
error: TypeError: Cannot read property 'body' of undefined  
    at replaceUrlForCreatedTaskId (/home/travis/build/AlbertoFdzM/another-todo-api/docs/hooks.js:10:89)

...

complete: 0 passing, 0 failing, 10 errors, 0 skipped, 6 total  
complete: Tests took 720719ms  
complete: See results in Apiary at: https://app.apiary.io/public/tests/run/91a01c82-f849-4736-8681-469d8e4d7ba9  
info: Backend server process exited  
npm ERR! Test failed. See above for more details.  
The command "npm test" exited with 1.  
Done. Your build exited with 1.

Note: Some logs traces have been omitted to improve readability. The whole log can be found in the Travis CI build report.

What has happened?

There are some good things and some bad thing to pay attention to. The first one is that Travis has made a build with NodeJS! It gives a lot of info about what is happening in that machine that is building the project in "the cloud" (OS version, node version, npm version, what things are installed in the system..)

Clone the repo: git clone --depth=50 --branch=post/06 https://github.com/AlbertoFdzM/another-todo-api.git AlbertoFdzM/another-todo-api
Install NodeJS: nvm install node
Install project dependencies: yarn (it detects that we have a yarn.lock file in the project)
Execute the tests: npm test ( default build command for Travis on NodeJS )
The tests fail: npm ERR! Test failed. See above for more details. 😢
The build fails: Done. Your build exited with 1. (hint: 1 is bad, 0 is good)

The problem:

(node:4653) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): MongoError: failed to connect to server [localhost:27017] on first connect [MongoError: connect ECONNREFUSED 127.0.0.1:27017]

It hasn't connected to the MongoDB database even though MongoDB was installed in the system:

MongoDB version  
MongoDB 3.2.16

This is because Travis doesn't start the service unless you tell it to do so.

Let's fix it.

`.travis.yml`

language: node_js  
node_js: "node"  
services: mongodb

Commit, push, check the build and... 🎉 Done. Your build exited with 0. (reminder: 0 is good)

Stop the machines, we can go home finally.

Wait... This post for a file with 3 lines only?

Yep, but there was already some things done, like well-defined dependencies in the package.json and tests defined using NodeJS standard practices with npm test.

Want more? Ok, there is more to do.

Travis CI Caching

The Travis config file can define which folders should be cached to improve build time. In this case, I'm going to cache the node_modules folder to reduce the time installing dependencies and also for yarn.

`.travis.yml`

language: node_js  
node_js: "node"  
services: mongodb  
cache:  
  directories:
    - "node_modules"
  yarn: true

Note: More info in Travis CI Caching documentation.

Travis Build Over Multiple NodeJS Versions

Travis CI can be configured to run against multiple NodeJS versions every time it builds to ensure the project works correctly in this environments.

For this project, it will run builds for the "latest" version, for NodeJS v4.x and NodeJS v7.x.

`.travis.yml`

language: node_js  
node_js:  
  - "node"
  - "7"
  - "4"
services: mongodb  
cache:  
  directories:
    - "node_modules"
  yarn: true

THE Travis Status Badge

This is the only very thing why all of us integrate our projects with Travis. To be the fanciest on GitHub wearing a bunch of blue/green badges saying that everything is ok and all is up to date.

To get the code click on the badge from the Travis CI page of the project, a dialog will appear showing you different options about which branch and in what kind of code you want the image snippet.

That image will show the updated build status of the selected branch.

`README.md`

# Another boring TODO API

[![Build Status](https://travis-ci.org/AlbertoFdzM/another-todo-api.svg?branch=master)](https://travis-ci.org/AlbertoFdzM/another-todo-api)

...

GitHub Code Supervision with Travis CI

Another cool thing Travis can do is to check every bit of code that changes in the project and avoid breaking changes to be merged into critical branches as well as notify about commits breaking the build.

Checking the commits history with Travis integrated, there appears checks and crosses indicating if the build executed for that commit went ok, and by clicking them you can go to the Travis build logs.

To avoid direct commits against a branch in GitHub and instead add code to it by Pull Requests you can activate the Branch Protection under the Project Settings inside the Branches section. Once there select the branch to protect and check "Protect this branch", "Require status checks to pass before merging", "Require branches to be up to date before merging", "continuous-integration/travis-ci" and "Include administrators".

By this way, all the code to be modified in that branch has to pass through a PR and then complete a successful build with Travis.

Conclusion

Travis CI is perfect to ensure the sanity of your code and to maintain good practices against the project, it also helps to detect possible bugs caused by refactors or changes in the functionality of the project. But that's not all, with advanced builds you could make deploys to production servers or build a compiled version for the end-user.

As always, the generated code from this article is on GitHub.

Clean Google Analytics Metrics

Alberto Fernandez Medina — Mon, 27 Nov 2017 11:39:02 +0000

So here is what happened. I went to my analytics panel and I checked my monthly visits. What did I saw?

That peak annoyed me, so I decided to investigate it.

Find Analytics Anomaly with Filters

What I do to identify why I have that peak in analytics is by trying to isolate it using analytics dynamic filters.

Filter by Date

First by isolating the date. If this is not the case there are more ways to isolate it that I will expose later.

There you are little bastard

In this case, it seems like the anomaly has happened in a very particular moment of the day like someone was doing a lot of requests to the web in a small fraction of the time.

Filter by City or Country

Now looking at the table of metrics filtered by City there is a particular one with a lot of requests.

Zaporozhye, Ukraine

That could be a great follower of my blog but I will be a little reluctant and investigate a little more.

Filter by Network

Just to ensure that these Ukrainian visits are reliable I'm going to look at the Network section on the left panel under Audience and then Technology.

Looking at the table it seems that my Ukrainian visits are being provided by ovh hosting inc. which is strange because that is my actual hosting provider. And looking at the bounce rate for those visits that is 100% it will mess the metrics changing the real user bounce rate.

To ensure that this is my machine I check the Hostname dimension (the link is on top of the table).

There only appears my hostname. Sometimes these anomalies are caused by spam bots or crawlers and you could identify them in this view. This time seems that the problem is coming from my hosting provider.

Filtering Analytics to get Clean Metrics

So now that I've recap a lot of info about what is going on with the metrics I can create some filters to ensure that my metrics are clean next time I check them.

First thing is to create a "Master" view that is going to have all the filters avoiding spam traffic and annoying stuff and I would leave the original view renamed to "Unfiltered" to compare its traffic time to time with "Master".

The way to create views is in the Admin section with the property selected by clicking on the VIEW select box and then on "Create New View". Once it is created the filters could be applied by clicking on the Filters section.

Create Filters in Google Analytics

Google Analytics offers tons of ways to filter our metrics, not only to clean them but also to have a custom type of views that could be used for different purposes.

The first filter I'm going to need is to exclude all the traffic that could come from unknown hostnames.

Then a filter for my annoying Hosting provider.

And finally to ensure that Crawlers doesn't pollute my metrics, one for them.

Here you have the expression I used for the crawlers:

site-auditor\.online|speedup-my\.site|website-analytics\.online

You can detect them under the Acquisition section on Referrals.

Note: Filters doesn't clean info of your metrics from the past, so they will start working from the moment you apply them.

Keep it clean!

That's all, now on it's up to you to improve it. You can read more on Google Analytics Filter Documentation

Testing an API Against its Documentation

Alberto Fernandez Medina — Thu, 23 Nov 2017 11:18:08 +0000

This article covers how to run tests based on the API docs against an Express NodeJS API documented with API Blueprint using Dredd testing tool.

Note: This is the 5th post of a series of post about Building APIs With Express. Based on my last post about Documenting your API with API Blueprint I'll continue developing over the generated code.

So last time I documented the Another TODO API using API Blueprint and now I'm going to take advantage of that to have some test against the API to ensure documentation is up to date with the actual API code. For this task, I'm going to be using Dredd.

Dredd

Dredd is a tool for testing APIs using their own documentation.

Installing Dredd Locally

To install Dredd for this use case it is needed to have installed:

NodeJS
NPM

Then on the terminal:

npm i -g dredd

Now Dredd can be used as CLI tool.

Configuring Dredd

These Dredd guys are amazing to the point that the only thing needed to be done to start working with Dredd is by running the next line:

dredd init

? Location of the API description document docs/main.apib
? Command to start API backend server e.g. (bundle exec rails server) npm start
? URL of tested API endpoint http://127.0.0.1:3000/v1
? Programming language of hooks nodejs
? Do you want to use Apiary test inspector? Yes
? Please enter Apiary API key or leave empty for anonymous reporter
? Dredd is best served with Continuous Integration. Create CircleCI config for Dredd? No

Configuration saved to dredd.yml

Run test now, with:

  $ dredd

Some notes about what has been done here. Dredd has created a dredd.yml file at the root of the project with a bunch of properties based on the replies it has received.

`dredd.yml`

# https://dredd.readthedocs.io/en/latest/usage-cli.html#configuration-file
dry-run: null  
hookfiles: null  
language: nodejs  
sandbox: false  
server: npm start # Command to start the API server  
server-wait: 3  
init: false  
custom:  
  apiaryApiKey: ''
names: false  
only: []  
reporter: apiary  
output: []  
header: []  
sorted: false  
user: null  
inline-errors: false  
details: false  
method: []  
color: true  
level: info  
timestamp: false  
silent: false  
path: []  
hooks-worker-timeout: 5000  
hooks-worker-connect-timeout: 1500  
hooks-worker-connect-retry: 500  
hooks-worker-after-connect-wait: 100  
hooks-worker-term-timeout: 5000  
hooks-worker-term-retry: 500  
hooks-worker-handler-host: 127.0.0.1  
hooks-worker-handler-port: 61321  
config: ./dredd.yml # Source of Dredd config file  
blueprint: docs/main.apib # The API Blueprint file to get API definitions  
endpoint: 'http://127.0.0.1:3000/v1' # The base URL where the test will run

I've commented the lines that I found most important for this step but all the info can be found in Dredd Configuration File Documentation.

Running Tests with Dredd

Now that the project has a config file and Dredd knows how to run the server this is the next command to execute (I think you already know):

dredd

When executing the tests there will appear a report about what Dredd has found:

info: Configuration './dredd.yml' found, ignoring other arguments.  
warn: Apiary API Key or API Project Subdomain were not provided. Configure Dredd to be able to save test reports alongside your Apiary API project: https://dredd.readthedocs.io/en/latest/how-to-guides/#using-apiary-reporter-and-apiary-tests  
info: Starting backend server process with command: npm start  
info: Waiting 3 seconds for backend server process to start

...

info: Beginning Dredd testing...  
GET /v1/tasks 200 13.427 ms - 1450  
fail: GET (200) /tasks duration: 58ms

...

info: Displaying failed tests...  
fail: GET (200) /tasks duration: 58ms  
fail: headers: Header 'content-type' has value 'application/json; charset=utf-8' instead of 'application/json'

request:  
method: GET  
uri: /tasks  
headers:  
    User-Agent: Dredd/4.4.0 (Windows_NT 10.0.15063; x64)
    Content-Length: 0

body:

expected:  
headers:  
    Content-Type: application/json

body:  
[
  {
    "__v": 0,
    "updatedAt": "2017-01-05T17:53:37.066Z",
    "createdAt": "2017-01-05T17:53:37.066Z",
    "_id": "586e88217106b038d820a54e",
    "isDone": false,
    "description": "test"
  },
  ...
]
statusCode: 200

actual:  
statusCode: 200  
headers:  
    x-powered-by: Express
    content-type: application/json; charset=utf-8
    content-length: 1450
    etag: W/"5aa-Oh/N4fD/Is1M3QO9MzB/QQaYxDU"
    date: Fri, 01 Sep 2017 15:36:43 GMT
    connection: close

body:  
[{"_id":"59a2fe039c2adf0e90acca12","updatedAt":"2017-08-27T17:14:43.564Z","createdAt":"2017-08-27T17:14:43.564Z","__v":0,"isDone":false,"description":"Buy milk"},{"_id":"59a2fe0f852c331148011df3","updatedAt":"2017-0
8-27T17:14:55.731Z",...  
}]

...

complete: 0 passing, 6 failing, 0 errors, 0 skipped, 6 total  
complete: Tests took 815ms  
DELETE /v1/tasks/586e88337106b038d820a54f 404 1.128 ms - 539  
complete: See results in Apiary at: https://app.apiary.io/public/tests/run/423b37ad-1dd8-499c-9124-4320ea0f7911  
info: Backend server process exited

Also, at the end, if the dredd config file has the reporter as apiary, there will be a link (similar to https://app.apiary.io/public/tests/run/123456) to this page:

Note: The provided link is a temporary page and will be removed after a while.

In this panel is a lot of info about how the tests did go. Another TODO API has some errors in the docs, one of them is the definition of content-type. Let's fix that and run the tests again.

After the changes and running dredd this is the new report:

This time some of the endpoints have been validated but not all. The endpoints that require a task ID to work are returning 404 responses and causing the test to fail. this is because the task IDs specified in the API docs are only exposed as an example and doesn't really exists in the DB. Here is when Dredd hooks come handy.

Dredd Hooks

The hooks allow executing some code between, before or after each test case. This time I'm going to use one hook to get the ID of the task created on the "Create a New Task" definition to use that created task for the tests that need a taskId to work.

`docs/hooks.js`

// Import the hooks library to work with them (injected by dredd)
const hooks = require('hooks')  
// Create some shorthand functions for the hooks
const after = hooks.after  
const before = hooks.before

// Because the action is going to be the same in all the hooks lets create a function
const replaceUrlForCreatedTaskId = function (transaction) {  
  // Gets the taskId from the response object
  let taskId = JSON.parse(responseStash['Tasks > Tasks Collection > Create a New Task'].body)._id
  // Gets the predefined request url
  let url = transaction.fullPath

  // Replaces the wrong taskId with the correct one
  transaction.fullPath = url.replace('586e88337106b038d820a54f', taskId)
}

// Instantiates an object to store the responses
let responseStash = {}

// Sets a hook to be executed after creating a task to store the response
after('Tasks > Tasks Collection > Create a New Task', function (transaction) {  
  // Stores the response inside the temporary object
  responseStash[transaction.name] = transaction.real
})

// Sets hooks before the requests are made to replace the URLs
before('Tasks > Task > View a Task', replaceUrlForCreatedTaskId)  
before('Tasks > Task > Edit a whole Task', replaceUrlForCreatedTaskId)  
before('Tasks > Task > Edit a Task partially', replaceUrlForCreatedTaskId)  
before('Tasks > Task > Delete a Task', replaceUrlForCreatedTaskId)

After setting the hooks the dredd.yml file needs to be modified.

`dredd.yml`

# https://dredd.readthedocs.io/en/latest/usage-cli.html#configuration-file
dry-run: null  
hookfiles: ./docs/hooks.js # Here, we are telling dredd where are the hooks files  
language: nodejs  
sandbox: false  
...

Now running the tests again:

info: Displaying failed tests...  
fail: PATCH (200) /tasks/586e88337106b038d820a54f duration: 11ms  
fail: body: Can't validate. Expected body Content-Type is application/json; charset=utf-8 but body is not a parseable JSON: Parse error on line 1:  
+ Attributes (Task)
^
Expecting 'STRING', 'NUMBER', 'NULL', 'TRUE', 'FALSE', '{', '[', got 'undefined'

It is complaining about the line 118 of the main.apib file:

+ Response 200 (application/json; charset=utf-8)

        + Attributes (Task)

There is being used a data structure for the response field but it's indented by 8 spaces , and for API Blueprint documents that means a block of code, so by reducing it to 4 and running the tests again:

info: Beginning Dredd testing...  
info: Found Hookfiles: 0=E:\develop\another-todo-api\docs\hooks.js  
GET /v1/tasks 200 14.604 ms - 5636  
pass: GET (200) /tasks duration: 69ms  
POST /v1/tasks 201 26.640 ms - 160  
pass: POST (201) /tasks duration: 48ms  
GET /v1/tasks/59a9a413bfa907076857eae2 200 4.018 ms - 160  
pass: GET (200) /tasks/586e88337106b038d820a54f duration: 110ms  
PUT /v1/tasks/59a9a413bfa907076857eae2 200 7.289 ms - 159  
pass: PUT (200) /tasks/586e88337106b038d820a54f duration: 21ms  
pass: PATCH (200) /tasks/586e88337106b038d820a54f duration: 15ms  
PATCH /v1/tasks/59a9a413bfa907076857eae2 200 2.659 ms - 164  
pass: DELETE (204) /tasks/586e88337106b038d820a54f duration: 30ms  
complete: 6 passing, 0 failing, 0 errors, 0 skipped, 6 total  
complete: Tests took 579ms  
DELETE /v1/tasks/59a9a413bfa907076857eae2 204 3.519 ms - -  
complete: See results in Apiary at: https://app.apiary.io/public/tests/run/ca648983-2438-4b7b-b720-352bc00a79c8  
info: Backend server process exited

Smooth like butter

NPM Test Script

Until now I've been using Dredd from my global installation but it's a better idea to include it as a dev dependency and create an npm test script.

npm i -D dredd

`package.json`

...
  "scripts": {
    "lint": "eslint **/*.js",
    "start": "set DEBUG=another-todo:* && node bin/www",
    "test": "dredd"
  },
...

Conclusion

Dredd is a good tool to maintain your API Doc updated and make DDD (Documentation Driven Development).

Anyway, you can check the generated code on GitHub.

Happy coding <3!

Documenting your API with API Blueprint

Alberto Fernandez Medina — Mon, 20 Nov 2017 10:43:17 +0000

This article covers how to document an API REST using API Blueprint standard providing API usage info to future clients. It can also be helpful to design the structure of future API endpoints before start its development.

Note: This is the 4th post of a series of post about Building APIs With Express. Based on my last post about Mongoose, MongoDB and Express I'll continue developing over the generated code.

OMG, a lot of time has passed since my last commit and now when I look at the API there are some endpoints that I don't remember very well since the last time I developed them. Let's fix it now that I understand most of it by documenting the API using API Blueprint syntax.

API Blueprint is a very basic standard based on MSON (Markdown Syntax for Object Notation) and due to its relative simplicity to write it could be easily maintainable along the life of an API.

Documenting right

I'm going to create a new folder in my project called docs to store all the documentation about my TODO API, and "why is this? in the same repo as your code?" may you ask, well this is because I think the docs files should be as close as possible to your code to ensure that they are updated and maintained by whom is developing the API. Also because I could use them to test the API against the documentation using some nice tools.

Let's stop chattering and start coding!

Defining the API

First I'm going to define the API main info:

`/docs/main.md`

FORMAT: 1A

# Another TODO

Another TODO API is that, another TODO API.

In the first line, I'm setting the format (1A) used for the document, the name for my API and a small description. That was easy, time to define the API resources after the API general description.

API Resources

FORMAT: 1A

...

# Group Tasks

Resources related to the tasks in the API.

## Tasks Collection [/tasks]

Note: Mind the ellipsis ... as obviate code.

Now here are a couple of keywords that will define our API schema, the first one is Group that is defining a section to categorize some resource and the other one is the [/tasks] definition at the end of the second header that is defining an endpoint. Now the actions.

Actions

...

### List All Tasks [GET]

+ Response 200 (application/json)

        [
          {
            "__v": 0,
            "updatedAt": "2017-04-09T16:15:37.066Z",
            "createdAt": "2017-04-09T16:15:37.066Z",
            "_id": "586e88217106b038d820a54e",
            "isDone": false,
            "description": "test"
          },
          {
            "__v": 0,
            "updatedAt": "2017-04-09T16:15:37.067Z",
            "createdAt": "2017-04-09T16:15:37.067Z",
            "_id": "586e88337106b038d820a54f",
            "isDone": false,
            "description": "test"
          }
        ]

A lot of stuff happening on this lines, first there is a keyword in the header [GET] indicating the verb of the request and after that it's a response definition (they must start with +, * or -, like a markdown list item) followed by the status code 200 (mandatory) and the response Content-Type application/json (optional), and at the end an example of response body (example objects must be indented with 8 spaces or 2 tabs).

What about the POST?

...

### Create a New Task [POST]

+ Attributes
    + description: `Buy milk` (string) - Task description
    + isDone: false (boolean, required) - Done status

+ Request (application/json)

        {
          "description": "Buy milk",
          "isDone": false
        }

+ Response 201 (application/json)

        {
          "__v": 0,
          "updatedAt": "2017-04-09T16:30:42.010Z",
          "createdAt": "2017-04-09T16:30:42.010Z",
          "_id": "586e88337106b038d820a54f",
          "isDone": false,
          "description": "Buy milk"
        }

Very similar to the GET one but this time I've also specified the Request and Attributes definition.

In Attributes there is a list of items that represent the possible properties for the request body each one with the prop name, an example value, the type, if is required and a small description.

In Request I've defined an example of a request body object.

Time to deal with URI params

URI Params

For the resources that have to be accessed by attacking an URL with params (/tasks/:id in my case) there is a way to define them:

## Task [/tasks/{taskId}]

+ Parameters

  + taskId: `586e88337106b038d820a54f` (string)

### View a Task [GET]

+ Response 200 (application/json)

        {
          "__v": 0,
          "updatedAt": "2017-04-09T16:30:42.010Z",
          "createdAt": "2017-04-09T16:30:42.010Z",
          "_id": "586e88337106b038d820a54f",
          "isDone": false,
          "description": "Buy milk"
        }

The properties defined in the URL with braces like {taskId} will be related to the definitions with the same name in the Parameters section. The Parameters section uses the same nomenclature as Attributes.

Data Structures

It is a bit of a harsh to define in each section the same response so you can define a Data Structures section in your docs to store some basic data structures.

## Data Structures

### Task

+ _id: `586e88337106b038d820a54f` (string, required) - Task's ID
+ description: `Buy more milk` (string, required) - Task's description
+ isDone: false (boolean, required) - Done status
+ createdAt: `2017-04-09T16:30:42.010Z` (string, required) - Task's created date
+ updatedAt: `2017-04-09T16:30:42.010Z` (string, required) - Task's update date

And then reuse them on your endpoint definitions.

### Edit a Task partially [PATCH]

+ Attributes
    + description: `Buy more milk` (string) - Task description
    + isDone: true (boolean) - Done status

+ Request (application/json)

        {
          "description": "Buy more milk"
        }

+ Response 200 (application/json)

        + Attributes (Task)

Here in the Response definition, I have used my Attributes data structure.

That's it!

I think I've covered all the basic cases by now, you can read this Advanced Tutorial about API Blueprint and define a much more robust API.

As always you can check the code on GitHub and you can review the Another TODO API docs in Apiary

Mongoose, MongoDB and Express

Alberto Fernandez Medina — Wed, 15 Nov 2017 10:05:32 +0000

First steps on ExpressJS API development to connect to a MongoDB database and start managing data using endpoints.

Note: This is the 3rd post of a series of post about Building APIs With Express. Based on my last post about API Routing with Express I'll continue developing over the generated code.

Last time, the awesome TODO API was leaved with a nice API Routing hierarchy, but! And this is an important "but". I didn't store any kind of data for future use, it's only storing the TODOs in temporal memory so once the server stops all the info is lost.

This post was first published on onlythepixel.com

Requirements

For this posts, I'll need to have installed on my machine MongoDB to being able to develop my API with real connections in my local environment.

Note: I need to pay attention to have my MongoDB up and running to being able to work with it.

Also, I'm going to need Mongoose as a dependency of my project, this package will help me with the DB communication and data models:

yarn add mongoose

Mongoose connection to MongoDB

First I need to let mongoose connect to my local MongoDB so I'm going to create a new script to take this job.

`src/db.js`

const mongoose = require('mongoose')
const debug = require('debug')
const log = debug('another-todo:database')
const error = debug('another-todo:database:error')

// First I define my DB URI or
// make my script take it from the env variables
const DB_URI = process.env.DB_URI || 'mongodb://localhost/another-todo'

// Define some basic methods to
// connect/disconnect to the DB
const db = {

  connect () {
    return mongoose.connect(DB_URI)
  },

  disconnect () {
    return mongoose.connection.close(() => {
      process.exit(0)
    })
  }
}

// This let mongoose use the node's default promises
mongoose.Promise = global.Promise

// Logs for our app
mongoose.connection.on('connected', () => {
  log('Mongoose connection open to ' + DB_URI)
})

// More logs...
mongoose.connection.on('disconnected', () => {
  log('Mongoose disconnected')
})

// Logs that I hope to not see
mongoose.connection.on('error', (err) => {
  error(err)
})

// Handle process terminations
// this ensures that there is any connection
// open with DB when I stop the app
process
  .on('SIGINT', db.disconnect)
  .on('SIGTERM', db.disconnect)

// finally I only expose the methods to being used by my app script
module.exports = db

Now I only need to use my db script on my app.

`src/index.js`

const express = require('express')
const logger = require('morgan')
const bodyParser = require('body-parser')
const app = express()
const v1 = require('./v1')
const db = require('./db')

// Connect to DB!!
db.connect()

// Middlewares
...

Mongoose Models

Now it's time to define the first mongoose model, at this moment the only model or relevant data to store in DB are my tasks so so I only going to need the model.

I'm going to use the same data structure that I used in my last post.

`src/models/task.js`

const mongoose = require('mongoose')
const Schema = mongoose.Schema

// I'm going to define a new schema
// Here is where I define the properties
// that my data is going to have
// along with its validations 
const taskSchema = new Schema({

  // A property 'description' of type string
  // with a default to a empty string
  description: {
    type: String,
    default: ''
  },

  // And a boolean property with false as default
  isDone: {
    type: Boolean,
    default: false,
    required: true
  }

}, {timestamps: true})

module.exports = mongoose.model('Task', taskSchema)

Note: that timestamps let me not having to define a property createdAt or updatedAt because it is going to add this value once that property is set to true.

Now is time to make use of this model in my API.

`src\v1\tasks.js`

const router = require('express').Router()
const Task = require('../models/task')

router.route('/')

  .get((req, res, next) => {
    // I exec the find without conditions 
    // to retrieve all my tasks
    Task.find((err, tasks) => {
      if (err) return next(err)

      return res.json(tasks)
    })
  })

  .post((req, res, next) => {
    Task.create(req.body, (err, task) => {
      if (err) return next(err)

      return res.status(201).json(task)
    })
  })

  .delete((req, res, next) => {
    // This method is similar to find but instead
    // it removes all the occurrences 
    Task.remove((err) => {
      if (err) return next(err)

      return res.status(204).end()
    })

    res.status(204).end()
  })

router.param('taskId', (req, res, next, id) => {
  // Handle to find the requested resouce
  Task.findById(id, (err, task) => {
    if (err) return next(err)

    // If the task is not found then the app returns a 404
    if (!task) {
      err = new Error('Task not found')
      err.status = 404
    } else {
      req.task = task
    }

    return next(err)
  })
})

router.route('/:taskId')

  .get((req, res, next) => {
    return res.json(req.task)
  })

  .put((req, res, next) => {
    // I'm not using req.task.update() because
    // that method doesn't return the task on the callback
    Task.findByIdAndUpdate(req.task.id, {
      $set: req.body
    }, {
      // Returns the updated task
      new: true,
      // Set the whole document even if we are not
      // receiving all the properties
      overwrite: true,
      // Run validations if we have them
      runValidators: true
    }, (err, task) => {
      if (err) return next(err)

      return res.json(task)
    })
  })

  .patch((req, res, next) => {
    Task.findByIdAndUpdate(req.task.id, {
      $set: req.body
    }, {
      new: true,
      runValidators: true
    }, (err, task) => {
      if (err) return next(err)

      return res.json(task)
    })
  })

  .delete((req, res, next) => {
    Task.findByIdAndRemove(req.task.id, (err) => {
      if (err) return next(err)

      res.status(204).end()
    })
  })

module.exports = router

Note: You can check the Mongoose API docs for info about its different methods.

Now it's time to try it!

cURL

$ curl -X GET "http://localhost:3000/v1/tasks"

[]

$ curl -X POST "http://localhost:3000/v1/tasks" \
> -H "Content-Type: application/x-www-form-urlencoded" \
> -d 'description=test'

{
    "__v": 0,
    "updatedAt": "2017-01-05T17:53:37.066Z",
    "createdAt": "2017-01-05T17:53:37.066Z",
    "_id": "586e88217106b038d820a54e",
    "isDone": false,
    "description": "test"
}

$ curl -X POST "http://localhost:3000/v1/tasks" \
> -H "Content-Type: application/x-www-form-urlencoded" \
> -d 'description=test'

{
    "__v": 0,
    "updatedAt": "2017-01-05T17:53:55.067Z",
    "createdAt": "2017-01-05T17:53:55.067Z",
    "_id": "586e88337106b038d820a54f",
    "isDone": false,
    "description": "test"
}
$ curl -X GET "http://localhost:3000/v1/tasks"

[
    {
        "__v": 0,
        "updatedAt": "2017-01-05T17:53:37.066Z",
        "createdAt": "2017-01-05T17:53:37.066Z",
        "_id": "586e88217106b038d820a54e",
        "isDone": false,
        "description": "test"
    },
    {
        "__v": 0,
        "updatedAt": "2017-01-05T17:53:55.067Z",
        "createdAt": "2017-01-05T17:53:55.067Z",
        "_id": "586e88337106b038d820a54f",
        "isDone": false,
        "description": "test"
    }
]

$ curl -X DELETE -i "http://localhost:3000/v1/tasks"

HTTP/1.1 204 No Content
X-Powered-By: Express
Date: Thu, 05 Jan 2017 17:54:47 GMT
Connection: keep-alive

$ curl -X POST "http://localhost:3000/v1/tasks" \
> -H "Content-Type: application/x-www-form-urlencoded" \
> -d 'description=test'

{
    "__v": 0,
    "updatedAt": "2017-01-05T17:54:53.555Z",
    "createdAt": "2017-01-05T17:54:53.555Z",
    "_id": "586e886d7106b038d820a550",
    "isDone": false,
    "description": "test"
}

$ curl -X GET "http://localhost:3000/v1/tasks/586e886d7106b038d820a550"

{
    "_id": "586e886d7106b038d820a550",
    "updatedAt": "2017-01-05T17:54:53.555Z",
    "createdAt": "2017-01-05T17:54:53.555Z",
    "__v": 0,
    "isDone": false,
    "description": "test"
}

$ curl -X PATCH "http://localhost:3000/v1/tasks/586e886d7106b038d820a550" \
> -H "Content-Type: application/x-www-form-urlencoded" \
> -d 'description=amazing' 

{
    "_id": "586e886d7106b038d820a550",
    "updatedAt": "2017-01-05T17:56:06.879Z",
    "createdAt": "2017-01-05T17:54:53.555Z",
    "__v": 0,
    "isDone": false,
    "description": "amazing"
}

$ curl -X PATCH "http://localhost:3000/v1/tasks/586e886d7106b038d820a550" \
> -H "Content-Type: application/x-www-form-urlencoded" \
> -d 'isDone=true' 

{
    "_id": "586e886d7106b038d820a550",
    "updatedAt": "2017-01-05T17:56:24.328Z",
    "createdAt": "2017-01-05T17:54:53.555Z",
    "__v": 0,
    "isDone": true,
    "description": "amazing"
}

$ curl -X PUT "http://localhost:3000/v1/tasks/586e886d7106b038d820a550" \
> -H "Content-Type: application/x-www-form-urlencoded" \
> -d 'isDone=false' 

{
    "_id": "586e886d7106b038d820a550",
    "createdAt": "2017-01-05T17:56:40.478Z",
    "updatedAt": "2017-01-05T17:56:40.478Z",
    "isDone": false,
    "description": ""
}

$ curl -X DELETE -i "http://localhost:3000/v1/tasks/586e886d7106b038d820a550"

HTTP/1.1 204 No Content
X-Powered-By: Express
Date: Thu, 05 Jan 2017 17:57:35 GMT
Connection: keep-alive

$ curl -X GET "http://localhost:3000/v1/tasks"

[]

If the server stops and starts again the tasks still there, mission accomplished!

Note: I recommend to use Postman to test the API instead of cURL.

That all I think. You can check the code on GitHub.

API Routing with Express

Alberto Fernandez Medina — Wed, 06 Sep 2017 19:15:59 +0000

Note: This is the 2nd post of a series of post about Building APIs With Express.

Based on my last post about Making APIs with Node and Express I'll continue developing over the generated code.

So, I left the basement for my TODO API prepared. Now it's time to work in the different endpoints and HTTP verbs/methods that this API is going to use.

This post was first published on onlythepixel.com

`/v1/tasks`

I'm going to start building my API's endpoints with Tasks Collection.

`[GET] /v1/tasks`

First thing I need is to GET the list of tasks from my so innovative TODO API and I think that the best way to build it is by creating a new isolated express router instance.

`src/v1/tasks.js`

const router = require('express').Router()

/**
 * TODO: Store data in DB.
 */
let tasks = [
  {
    description: 'Another task',
    isDone: false,
    createdAt: Date.now()
  }
]

router.route('/')

  .get((req, res, next) => {
    return res.json(tasks)
  })

module.exports = router

Easy peasy! Now I need to mount that router on my API, I'm going to remove the old Let's TODO! message:

`src/v1/index.js`

const router = require('express').Router()
const tasks = require('./tasks')

router.use('/tasks', tasks)

module.exports = router

Let's try the new endpoint (Now that I have implemented yarn I can run the server with `yarn start` instead of `npm start`):bash curl -X GET localhost:3000/v1/tasks [ { "createdAt" : 1481985039988, "isDone" : false, "description" : "Another task" } ]``
Note: It's needed to restart the server if there have been changes in the code while it is running to see the changes.

Now I'll continue with the creation of a new task

`[POST] /v1/tasks`

It should be in the same router instance the GET method is. This time I'll need a new middleware to parse correctly the request body, body-parser (this time I'll install it with Yarn).

`bash yarn add body-parser `
Note: Same as execute npm i -S body-parser

And now it needs to be attached to the app

`src/index.js`

`javascript
const express = require('express')
const logger = require('morgan')
const bodyParser = require('body-parser')
const app = express()
const v1 = require('./v1')

/**

Middlewares */ app.use(logger('dev')) app.use(bodyParser.json()) app.use(bodyParser.urlencoded({ extended: true }))

...
_**Note:** It will inject data from the request intoreq.body`._

And now the request handler.

`src/v1/tasks.js`

`javascript
...

router.route('/')

.get((req, res, next) => {
return res.json(tasks)
})

.post((req, res, next) => {
const newTask = req.body

newTask.createdAt = Date.now()
newTask.isDone = false
tasks.push(newTask)

return res.status(201).json(newTask)

})

module.exports = router
`
Note: Take advantage of the HTTP status codes.

Done, let's try again with a POST request this time:
`bash
curl -X POST -H "Content-Type: application/json" --data '{"description": "Also another task more"}' localhost:3000/v1/tasks
{"description":"Also another task more","createdAt":1481986821539}

curl -X GET localhost:3000/v1/tasks
[
{
"createdAt" : 1481986807819,
"isDone" : false,
"description" : "Another task"
},
{
"createdAt" : 1481986821539,
"isDone" : false,
"description" : "Also another task more"
}
]
`

Time to delete! Due this is an endpoint pointing a collection when it receives a DELETE request it should delete all items of the collection.

`[DELETE] /v1/tasks`

`src/v1/tasks.js`

`javascript
...

.post((req, res, next) => {
const newTask = req.body

newTask.createdAt = Date.now()
tasks.push(newTask)

return res.json(newTask)

})

.delete((req, res, next) => {
tasks = []

res.status(204).end()

})

module.exports = router
`

Delete all the things!

`bash
curl -X DELETE -i localhost:3000/v1/tasks

HTTP/1.1 204 No Content
X-Powered-By: Express
ETag: W/"2-11FxOYiYfpMxmANj4kGJzg"
Date: Sat, 17 Dec 2016 17:13:07 GMT
Connection: keep-alive
`

I am done with this endpoint.

`/v1/tasks/:taskId`

Now it's time to handle the single task endpoint. Here I'm going to take advantage of an Express feature to parse URLs, for this case, to treat a segment of the URL as a parameter and assigning it the name taskId.

`taskId` param

I am going to define a new param for the tasks router to get a certain task passing the task ID in the URL.

`src/v1/tasks.js`

`javascript
...

router.route('/')

...

router.param('taskId', (req, res, next, id) => {
const task = tasks[id]
let err

if (!task) {
err = new Error('Task not found')
err.status = 404
} else {
req.task = task
}

return next(err)
})

module.exports = router
`

`[GET] /v1/tasks/:taskId`

Then I only need to reply with the found task in a new endpoint listening to any request aimed to /v1/tasks/:taskId meaning by :taskId whatever comes after the slash (IE: /v1/tasks/my-task-id OR /v1/tasks/01234).

`src/v1/tasks.js`

`javascript
...

router.param('taskId', (req, res, next, id) => {
...
})

router.route('/:taskId')

.get((req, res, next) => {
return res.json(req.task)
})

module.exports = router
`

Let's try it

`bash
curl -X GET localhost:3000/v1/tasks/0
{
"description" : "Another task",
"isDone" : false,
"createdAt" : 1481996187751
}

curl -X GET -i localhost:3000/v1/tasks/1234

HTTP/1.1 404 Not Found
X-Powered-By: Express
Content-Type: application/json; charset=utf-8
Content-Length: 1082
ETag: W/"43a-4d6NK29IKrV0B3jSAdQGvA"
Date: Sat, 17 Dec 2016 17:46:36 GMT
Connection: keep-alive
{
"stack" : "Error: Task not found\n at router.param (/develop/another-todo-api/src/v1/tasks.js:38:11)\n at paramCallback (/develop/another-todo-api/node_modules/express/lib/router/index.js:404:7)\n at param (/develop/another-todo-api/node_modules/express/lib/router/index.js:384:5)\n at Function.process_params (/develop/another-todo-api/node_modules/express/lib/router/index.js:410:3)\n at next (/develop/another-todo-api/node_modules/express/lib/router/index.js:271:10)\n at Function.handle (/develop/another-todo-api/node_modules/express/lib/router/index.js:176:3)\n at router (/develop/another-todo-api/node_modules/express/lib/router/index.js:46:12)\n at Layer.handle as handle_request\n at trim_prefix (/develop/another-todo-api/node_modules/express/lib/router/index.js:312:13)\n at /develop/another-todo-api/node_modules/express/lib/router/index.js:280:7",
"message" : "Task not found"
}
`

`[POST] /v1/tasks/:taskId`

Now it's important to pay attention here because the POST request to a specified resource in an API REST by definition should override completely the resource, meaning that if:
I do a GET to /v1/tasks/0 receiving:
`json { "description" : "Another task", "isDone" : false, "createdAt" : 1481996187751 } `
If I do a POST to /v1/tasks/0 with this data:
`json { "isDone": true } `
The next time I do a GET to /v1/tasks/0 I'll receive the next response:
`json { "isDone": true } `
The proper way a client should make a POST to an API resource is by providing all the resource info in the request to avoid the lose of info.

Now go back to code!

`src/v1/tasks.js`

`javascript
...
.post((req, res, next) => {
const updatedTask = req.body

tasks[req.params.taskId] = updatedTask

return res.json(updatedTask)

})
...
`

`[PATCH] /v1/tasks/:taskId`

Now the PATCH request is the one used to update partially a resource in an API REST.

`src/v1/tasks.js`

`javascript
...
.patch((req, res, next) => {
for (let prop in req.body) {
tasks[req.params.taskId][prop] = req.body[prop]
}

return res.json(tasks[req.params.taskId])

})
...
`

Let's try this one with curl:
`bash curl -X PATCH -H "Content-Type: application/json" --data '{"isDone": true}' localhost:3000/v1/tasks/0 { "isDone" : true, "description" : "Another task", "createdAt" : 1481998868351 } `

Oh yeah!

`[DELETE] /v1/tasks/:taskId`

I think there's no much to explain here, is pretty much the same as the DELETE for the whole collections instead that this one only deletes one resource.

`src/v1/tasks.js`

`javascript
...
.delete((req, res, next) => {
tasks.splice(req.params.taskId, 1)

res.status(204).end()

})
...
`

End of the route

Well, I think that with this the awesome Another TODO API is completely functional, maybe I should care about that the info isn't being stored anywhere and every time the server stops I lose it all, but that'll be another time!

Comment and check the code on GitHub!

Making APIs with Node and Express

Alberto Fernandez Medina — Fri, 01 Sep 2017 19:48:33 +0000

I'm going to make a simple API with Node and Express, specifically an API for a TODOs app.

This post was first published on my blog, onlythepixel.com

Project Boilerplate

So I start a new Node project with the name another-todo-api in my terminal

mkdir another-todo-api && cd $_
git init
echo 'Another boring TODO API' > README.md
npm init -y
echo 'node_modules
*.log' >> .gitignore
npm i -S express
git add .
git commit -m 'First commit'

Note: npm i -S is the same as npm install --save but in the shorter way.

Simple! I've started a new git repo with an empty README file and a new npm package that has express as a dependency. Let's play a little with Express.

I like to have all my source code inside a src folder:

mkdir src
touch src/index.js

`src/index.js`

const express = require('express')
const app = express()

module.exports = app

Note: Due to the coolness of this article all the javascript code will be shown in ES2015 (So it's recommended to use Node v6 or later) and I'll be using Standard Code Style for the javascript.

Now to run the server I don't like to start it from the index.js file directly, instead, I prefer to run it through an external bin file (like Express does in its generator).

`bin/www`

#!/usr/bin/env node
/**
 * Created from https://github.com/expressjs/generator/blob/d07ce53595086dd07efb100279a7b7addc059418/templates/js/www
 */

/**
 * Module dependencies.
 */
const http = require('http')
const debug = require('debug')('another-todo:server')
const app = require('../src')

/**
 * Get port from environment and store in Express.
 */

const port = normalizePort(process.env.PORT || '3000')
app.set('port', port)

/**
 * Create HTTP server.
 */
const server = http.createServer(app)

/**
 * Normalize a port into a number, string, or false.
 */
function normalizePort (val) {
  const port = parseInt(val, 10)

  // named pipe
  if (isNaN(port)) return val

  // port number
  if (port >= 0) return port

  return false
}

/**
 * Event listener for HTTP server "error" event.
 */
function onError (error) {
  if (error.syscall !== 'listen') throw error

  const bind = typeof port === 'string'
    ? 'Pipe ' + port
    : 'Port ' + port

  // handle specific listen errors with friendly messages
  switch (error.code) {
    case 'EACCES':
      console.error(bind + ' requires elevated privileges')
      process.exit(1)
      break
    case 'EADDRINUSE':
      console.error(bind + ' is already in use')
      process.exit(1)
      break
    default:
      throw error
  }
}

/**
 * Event listener for HTTP server "listening" event.
 */
function onListening () {
  const addr = server.address()
  const bind = typeof addr === 'string'
    ? 'pipe ' + addr
    : 'port ' + addr.port
  debug('Listening on ' + bind)
}

/**
 * Listen on provided port, on all network interfaces.
 */
server.listen(port)
server.on('error', onError)
server.on('listening', onListening)

And then bind this file to my npm scripts.

`package.json`

  ...
  "scripts": {
    "start": "set DEBUG=another-todo:* && node bin/www",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  ...

Also I'll need the package debug as dependency of my project due that I'm using it in my www file:

npm i -S debug

After that I can try my brand new Express server:

npm start

> another-todo-api@0.0.0 start /develop/another-todo-api
> set DEBUG=another-todo:* && node bin/www

  another-todo:server Listening on port 3000 +0ms

By default this little guy should be listening on the port 3000 of my computer. If I access with some browser to http://localhost:3000 I'll receive a sad Cannot GET /.

Express Router

Time to make this guy have some voice to being able to reply me when I ask for something. For that I'll use the Express Routers to build up my TODO API pieces.

`src/v1/index.js`

const router = require('express').Router()

router.route('/')
  .get((req, res, next) => {
    return res.json({
      message: 'Let\'s TODO!'
    })
  })

module.exports = router

Note: that thing of v1 is because it's a good practice to implement a version system in APIs.

Just a simple reply to a GET request, if I go to http://localhost:3000 again, nothing happens... Because I need to mount this router path in my Express app.

`src/index.js`

const express = require('express')
const app = express()
const v1 = require('./v1')

/**
 * Routes
 */
app.use('/v1', v1)

module.exports = app

This would work just fine! If I visit http://localhost:3000/v1 this thing will have voice now:

{"message":"Let's TODO!"}

Middlewares

Now I'm going to add some middleware to avoid contact with Systems that doesn't support JSON format.

`src/index.js`

const express = require('express')  
const app = express()  
const v1 = require('./v1')

/**
 * Ensure JSON acceptance
 */
app.use((req, res, next) => {
  let err

  if (!req.accepts('json')) {
    err = new Error('Not Acceptable')
    err.status = 406
  }

  return next(err)
})

/**
 * Routes
 */
...

Now that I have a middleware that is returning an error I can test it with curl (probably you already have it in your terminal).

curl -i -H "Accept: text" localhost:3000

HTTP/1.1 406 Not Acceptable
X-Powered-By: Express
X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8
Content-Length: 1052
Date: Sun, 11 Dec 2016 18:40:03 GMT
Connection: keep-alive

Error: Not Acceptable<br> &nbsp; &nbsp;at app.use (/develop/another-todo-api/src/index.js:9:11)<br> &nbsp; &nbsp;at Layer.handle [as handle_request] (/develop/another-todo-api/node_modules/express/lib/router/layer.js:95:5)<br> &nbsp; &nbsp;at trim_prefix (/develop/another-todo-api/node_modules/express/lib/router/index.js:312:13)<br> &nbsp; &nbsp;at /develop/another-todo-api/node_modules/express/lib/router/index.js:280:7<br> &nbsp; &nbsp;at Function.process_params (/develop/another-todo-api/node_modules/express/lib/router/index.js:330:12)<br> &nbsp; &nbsp;at next (/develop/another-todo-api/node_modules/express/lib/router/index.js:271:10)<br> &nbsp; &nbsp;at expressInit (/develop/another-todo-api/node_modules/express/lib/middleware/init.js:33:5)<br> &nbsp; &nbsp;at Layer.handle [as handle_request] (/develop/another-todo-api/node_modules/express/lib/router/layer.js:95:5)<br> &nbsp; &nbsp;at trim_prefix (/develop/another-todo-api/node_modules/express/lib/router/index.js:312:13)<br> &nbsp; &nbsp;at /develop/another-todo-api/node_modules/express/lib/router/index.js:280:7

Note: If I try it without the --header "Accept: text" it will reply my with the correct response.

Mind your language young man! It's answering me in HTML I need to parse that reply passing it through a Error Handler .

ErrorHandler

Now that my app has errors (in the good meaning) I need a ErrorHandler on my app.

`src/index.js`

...
/**
 * Routes
 */
app.use('/v1', v1)

/**
 * ErrorHandler
 */
app.use((err, req, res, next) => {
  res.status(err.status || 500)
    .json({
      message: err.message,
      stack: err.stack
    })
})

module.exports = app

Note: It's important to remember only to use that ErrorHandler only in development and try not to show so many info when it's a production environment.

If I ask my server again.

curl -i -H "Accept: text" localhost:3000

HTTP/1.1 406 Not Acceptable
X-Powered-By: Express
X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8
Content-Length: 1052
Date: Sun, 11 Dec 2016 18:42:12 GMT
Connection: keep-alive

{"message":"Not Acceptable","stack":"Error: Not Acceptable\n    at app.use (/develop/another-todo-api/src/index.js:9:11)\n    at Layer.handle [as handle_request] (/develop/another-todo-api/node_modules/express/lib/router/layer.js:95:5)\n
    at trim_prefix (/develop/another-todo-api/node_modules/express/lib/router/index.js:312:13)\n    at /develop/another-todo-api/node_modules/express/lib/router/index.js:280:7\n    at Function.process_params (/develop/another-todo-api/node_modules/express/lib/router/index.js:330:12)\n    at next (/develop/another-todo-api/node_modules/express/lib/router/index.js:271:10)\n    at expressInit (/develop/another-todo-api/node_modules/express/lib/middleware/init.js:33:5)\n    at Layer.handle [as handle_request] (/develop/another-todo-api/node_modules/express/lib/router/layer.js:95:5)\n    at trim_prefix (/develop/another-todo-api/node_modules/express/lib/router/index.js:312:13)\n    at /develop/another-todo-api/node_modules/express/lib/router/index.js:280:7"}

Now that's a good error reply.

Extras

I leaved some things pending on my code when building my API server, you can skip this part if you feel lazy about continue reading this crap.

Logging with Morgan

There are tons of middlewares packages for express, one very useful is Morgan, it's an HTTP request logger and it'll print in the terminal all the request that the server will receive.

npm i -S morgan

Then I need to attach it to my app.

`src/index.js`

const express = require('express')
const logger = require('morgan')
const app = express()
const v1 = require('./v1')

/**
 * Middlewares
 */
app.use(logger('dev'))

...

Now if I run my server and make some requests to it:

npm start

> another-todo-api@0.0.0 start /develop/another-todo-api
> set DEBUG=another-todo:* && node bin/www

  another-todo:server Listening on port 3000 +0ms
GET / 404 5.469 ms - 13
GET /favicon.ico 404 0.905 ms - 24
GET /v1 200 2.275 ms - 25

Linting

I said that I was using Standar code style fot the javascript code but I didn't bother to make me sure that this code style get used every time someone writes code on this project. The best way to do this is with some linter and for this I'm going to use ESLint.

First I need to install my development dependencies (because this tools are not going to be used in production):

npm i -D eslint eslint-config-standard eslint-plugin-standard eslint-plugin-promise

Note: npm i -D is the same as npm install --save-dev.

Now I need to define some configuration file on my project code.

`.eslintrc`

{
  "extends": "standard"
}

Note: Just that!

And I'm going to add a new npm script.

`package.json`

...
  "scripts": {
    "lint": "eslint **/*.js",
    "start": "set DEBUG=another-todo:* && node bin/www",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
...

Time to try it.

npm run lint

> another-todo-api@0.0.0 lint /develop/another-todo-api
> eslint **/*.js

Note: If nothing happens is because there's no errors, you can try to reproduce an error by adding some ; in some of the JS files.

There are several plugins for linting the code on the fly in the text editor, so by this way you don't need to run the linting npm script. In my case I use Atom with linter and linter-eslint packages.

Editorconfig

This is a very important tool, it avoids a lot of noise between commits on git or git diffs. Also it helps to keep the code format homogeneous among the project.

`.editorconfig`

# EditorConfig is awesome: http://EditorConfig.org

root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

As for the linting there is also plugins available for the usuals text editors. In the case of Atom there is the editorconfig package.

Yarn

Not long ago Yarn, a new dependency manager, got released and it's fully compatible with npm. Only needs to be installed and then just:

yarn

Note: It is the same as yarn install that is the same as npm install. You can check the Yarn vs. NPM command comparison.

There will appear a new file called yarn.lock that's info used by Yarn to improve the timing installing dependencies and if you red the first lines of the file all will be Crystal Clear:

# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.

From here I can start using Yarn instead NPM for dependencies and NPM scripts.

Enough!!!

This post is long enough to bore you so I'm going to stop here. Later!

Oh! Yes... you can check this code on the another-todo-api GitHub repo.