3/25/2015

[Book Review] AngularJS UI Development


Once again Packt graciously sent me AngularJS UI Development book for reviewing and I am grateful for that.
But I will be brief. It's one of the worst written "technical" book I've ever read.

  • silly chapter ordering and subject choices
  • chapter subjects are glanced over, chapters feel like unfinished copy/pasted tutorials
  • code samples should have never been approved during the review
    • separation of concerns is not respected most of the time
      • and by most of the time I mean 95% of the time, not 60%
    • there are so much state in these examples, everywhere
  • this book does not even talk about routing and state management
    • ... well, unless you wait until chapter 10 and consider a one-route single page application (SPA) good enough.
    • In a book about UI Development, view state management is essential so in my humble opinion the book should have started with it. 

When we think about AngularJS UI Development, the first library that come to mind is ui-router. Instead we have a chapter 3 about google maps integration, chapter 5 about ng-animate, chapter 6 about charts integration and so on...


Okay, let's stop there and just say that I won't recommend this book to anyone, ever.


If you are new to AngularJS and are looking for a serious book on that matter consider MEAN Web Development, at least this one is well written.
3/14/2015

[BrainDump] Versioning an HTTP API

I sometime share privately what I call a #BrainDump over a specific subject I just learned or thought about. A #BrainDump can be described as a snapshot of my current state of mind (or state of art in the current blog post) over a particular subject.

First step, let's specify an API version

    • ... in the header
      • cons:
        • requires an http client (curl/postman) to test endpoint
      • ... with accept (accept: application/vnd.haveibeenpwned+json; version=2.0)
        • pros:
          • allow the client to specify both a schema and a version
        • cons:
          • just like the other solutions, this one is also not standard: "Per the RFC, accept headers should only be used to specify the media type. Versioning is not media type, therefore using accept headers is IMO misuse.source
      • ... with user-defined header  (X-VersionX-Restful-Interface-Version)
    • ... in the URI
      • pros:
        • easy to try GET requests directly from the browser
      • cons:
        • not standard per HTTP RFC
        • does not respect REST principle
      • ... inside a sub-domain (v1.api.domain.com)
        • pros:
          • easy to configure backends with a reverse-proxy
      • ... inside the path 
        • format: /v1/
          • pros:
            • easy to configure backends with a reverse-proxy
          • used by:
        • format: /YYYYMMDD
          • pros:
            • the client does not need to remember API version
            • the client only asks for the API that was working at YYYYMMDD
          • cons:
            • between the client development and release the API may have changed
          • used by:
      • ... inside the query-string (?v=1)
        • wait, what?
    • ... once the request has been authenticated
      • assumption: each requests needs the be authenticated, then retrieve what API version the authenticated user has configured
      • pros:
        • easy to do analytics on API version usage
        • easy to inform users that access soon-to-be-removed API version
      • cons:
        • an authentication step is required
        • a user can only access to one API version at a time
        • no explicit contract between the client and the server 
        • the API version selection is hidden from the client
      • used by:

Then handle multiple API versions server-side

    • ... forwarding each request to the right API server using a reverse-proxy
      • pros:
        • stale API servers are easier to remove from production
      • cons:
        • it requires (at least) 2 running servers per API version
        • need to maintain multiple HTTP servers (branch) with security patches
        • need to maintain multiple running API servers in various versions
    • ... putting every version inside a single-code base, servers are load-balanced
      • each running server have to handle multiple-versions
      • pros:
        • a lot less duplicated code between handlers
        • easier server management
      • cons:
        • business models are often poluted with old behaviours
    • ... using an API migration middleware server (this is a work-in-progress)
      • assumption: the latest API version always exposes more data than the previous one
        • In other words the huge limitation of that approach is that changes HAVE TO be additive
      • how it works:
        • HTTP front <-> API Middleware Server (APIMS) <-> Up-to-date API Server (APIS)
          • for latency, both the APIMS and the APIS SHOULD be on the same node
          • for availability, of course both the APMS and APIS should be replicated across servers
        • Each HTTP request SHOULD go through the APIMS
          • if the request specify v4 and that latest API version is v6 the middleware
          • APIMS receiving request from client (asking for v4)
            •  -> up(req) (v4->v5)
              •  -> up(req) (v5->v6)
                •  -> forward request to APIS
                  • APIS (v6) process the request
                • <- APIS response
              • <- down(res) (v6->v5)
            • <- down(res) (v5->v4)
          • APIMS sending response to client
          • Note: it should be possible to bypass the APIMS if the requested API version is the latest one
        • a migration file CAN be implemented for each new version (vN-1->vN). Each migration file should implement the above interface
          • up(req: Request, next : Function(error))
            • used to update an API request from vN to vN+1
            • if an `error` is specified in `next` the APIMS can directly answer the request thus breaking the contract
          • down(res: Response, next: Function(error))
            • used to downgrade an API response from vN to vN-1
      • pros:
        • API versioning is decoupled from the API server
        • developers only needs to deploy the latest API version
        • devops only need to ensure the latest API version is running
      • cons:
        • does not handle every case 
          • e.g. a piece of data was available in v1 but is not available in v2 thus the middleware can't add it on the down stage

This post is simply an overview of documented practice, if you know (or better: use) other way to version HTTP API, don't hesitate to share them in the comment section below!
3/08/2015

[Book Review] MEAN Web Development

After my review of Getting Started With Grunt and Lodash essentials this time Packt Publishing contacted me to review MEAN Web Development. Since Redsmin was first built over the ME(A)N stack and a lot of our applications at Bringr are built using NodeJS/AngularJS I happily accepted the offer, below is the review I posted on amazon.


Chapter 1 Introduction to MEAN


This chapter begins with a brief introduction to the MEAN stack and is then a deep step by step guide on how to install and run MongoDB, NodeJS, NPM both on Windows, Mac OS X and Linux. It's the perfect starting point for newcomers. I will simply add that it's a better practice ? to install NodeJS using Node Version Manager (nvm) that with the official installation software.

Chapter 2 - Getting Started with NodeJS


After a brief history of why Ryan Dahl created NodeJS the author dives into explaining event-driven programming. You will learn how work an event loop and how a webserver with a non-blocking event-loop (nginx) differs from a blocking web-server (apache) in terms of concurrent access performance and memory consumption. Then you'll take a look at closures and why they are useful in callbacks. Finally you'll learn how to write your first NodeJS http server along with your first connect middleware.

Chapter 3 - Building an Express Web App

Time to go to the next step : writing your first Express application, managing sessions, using a template engine (EJS) and a routing scheme. This chapter takes the reader by the hand and is really descriptive on how to organize your application folder architecture and write your first application.
However instead of using configuration files by environments (e.g. production, staging and development) I would recommend the reader to use environment variables (using a module like common-env + autoenv) since it's a way more flexible approach. Another missing point is to warn the reader to add a "private:true" inside its package.json file otherwise it could publish its application on npm by mistake.

Chapter 4 - Introduction to Mongodb


Even if this chapter explains to new comers what MongoDB is, the author is clearly using too much superlative about MongoDB. It's important to recall that MongoDB is not a replacement for relational storage and that it must be used with care.

Chapter 5 - Introduction to Mongoose


Just like the previous chapter, this one is also well written. It explains each Mongoose features starting with schema, validation, virtuals, getter/setter and even DbRef. I would simply note that some conditionals in the code examples could be greatly simplified.

Chapter 6 - Managing User Auth Using Passport


Learn how to handle user creation/connection with PassportJS, using local auth or Facebook/Twitter/Google OAuth. The OAuth user creation mechanism described in the book does not allow a user to connect via multiple OAuth provider and is thus limited. The access_token refreshing mechanism, even if it's not implemented, should be at least given as an exercise for the reader.

Chapter 7 - Introduction AngularJS


Another really well written chapter, this time about AngularJS. From the history to the state of the art, you'll learn everything you need to know to build your first application with AngularJS from routing to services. Note that the authentication service code example does not respect the Inversion Of Control principle and should be rewritten to ask for $window.

Chapter 8 - Creating a MEAN CRUD Module


In this chapter, learn how to set CRUD (Create-Retrieve-Update-Delete) modules up from back (using mongoose) to front (using angularjs $ressource). The middleware approach to retrieve an article is subject to race-conditions. I will just add that a much more powerful alternative than ngressource is Restangular. Also I would advise the reader to prefer ui-router (built over a finite-state-machine with support for sub-views) over angular own router module.

Chapter 9 - Adding Real-time func. Using Socket.io


Next, learn how to communicate in real-time between the browser and the server using websocket. In order to do that you'll learn how to set socket.io up. Be careful about the socket.io session configuration example, the error management should really be improved.

Chapter 10 - Testing MEAN apps


Nice overview of what unit-testing and end-to-end (E2E) testing is about. You'll learn how to unit-test a MEAN application with Mocha and Karma using Jasmine as well as E2E testing with protactor.

Chapter 11 - Automating & Debugging MEAN Apps


The last chapter demonstrates how to configure grunt to automate code quality checking and testing. You will learn grunt, node-inspector (for nodejs debugging) and batarang (a browser extension for angularjs debugging).

Conclusion

MEAN Web Web Development is clearly a well written book that will be the perfect match for beginners in AngularJS and NodeJS!
« »
 
 
Made with on a hot august night.
http://bit.ly/1II1u5L