
A key to a good API design is good control of what data your controllers or API end points accepts. Another important key to a good design — is that you can take a brief look at your API end point and immediately understand how your request should look.



Now, of course you can validate all the request parameters inside the API end point itself. But this makes your end point messy and sort of violates the [SRP](https://en.wikipedia.org/wiki/Single_responsibility_principle) (your end point should not validate requests. It should only work with them and provide a response). Now, if you are old fashioned and work with XML requests / response, you can of course use XSD to validate your incoming requests. But we are in 2016 where JavaScript runs in your browser, your desktop environment, your media center, you smart watch, your smart home and soon in your brain implants. So we gonna use JSON!

*But, how do I validate JSON?* I’m glad you’ve asked. Meet [joi](https://github.com/hapijs/joi) by [hapijs](http://hapijs.com/). This small and awesome library can validate your JavaScript objects. It can do all kind of stuff like making sure that a specific key has only specific set of values, or that specific key is only required if another key exists and contains a specific value. So as always, RTFM.

We now have joi to validate our JSONs. But we still need to find an elegant way to put it inside the life cycle of our specific API end point. I’m too lazy to create a specific, generic NPM module so I’ve just dumped the current code I use in my project to a [gist](https://gist.github.com/skwee357/7e4ca3b913f4b1202f51d72fcb1ac0db). Feel free to use it or create a proper NPM module (don’t forget to mention me for being your inspiration ;)

The middleware is very simple. It defines a Bad Request Error that will be thrown if the incoming request is malformed, and what it does, it simply validate the request against a given *schema* (a bit later on that) and assigns the validated object (essentially this is *req.body* but with type conversions and modifiers applied, more on this in [joi API documentation](https://github.com/hapijs/joi/blob/v9.0.4/API.md#validatevalue-schema-options-callback)) to the req.schema (not the best name) so it can be accessed later on inside the API end point (or any next middleware in the chain).

Now lets talk about the schema and how to actually use this. Schema is just a JSON with joi rules. Lets say we have 2 API end points: One for user creation and one for user update. We define then 2 schema:

```js
module.exports = {
    create: Joi.object().keys({
        username: Joi.string().min(3).required(),
        password: Joi.string().min(3).required(),
        email: Joi.string().email().required()
    }),
    update: Joi.object().keys({
        username: Joi.string().min(3).optional()
    })
};
```

In order to create a new user we need to provide 3 required keys: username (at least 3 characters), password (at least 3 characters) and email (should be a real email). And in order to update a user we can just provide an optional new username (at least 3 characters) (side note: an empty request in such case is a valid request, it is up to your end point to make sure to do no-op if the request is empty). We then define our API end points like this:

```js
var SchemaValidationMiddleware = require('path/to/schema/middleware'),
    UserSchema = require('path/to/schema/user'),
    UserController = require('path/to/user/controller');

router.post('/users', SchemaValidationMiddleware.validate(UserSchema.create), UserController.createNew);

router.patch('/users/:id', SchemaValidationMiddleware.validate(UserSchema.update), UserController.edit);
```

And inside the controller / API end point we can use *req.schema* to access the validated schema and perform the required operations. And we can be sure that the controller / end point will be executed only if our request meets the schema we defined for it. The *UserController.createNew* will never be called if one of the keys we defined as required in our schema — missing, if they are mistyped, if there are keys that we are not expecting and etc.,

This gives the answer to the 2 design keys of a good API that I’ve outlined in the beginning:

- Controllers / end points only manipulates the request and provide a response. They are not used to validate the request. We can be sure that our controllers / end points will never be called with an invalid request.
- By looking at our *schema/user.js* we can immediately understand how our request should look. We also can give those files to our customers / put them in our API documentation.

You can extend this idea and provide validation for responses as well. By writing a joi schema for the response and adding another middleware after your actual API end point that will validate the response you want to send against a response schema, so this can help you to avoid cases where developers might mistype a response key for examples *usrename* instead of *username*. And also by having request and response schema — your API is essentially self documented.

Hope this helped you to become a better JavaScript Jedi! Please share and like! Leave a comment or hit me on [Twitter](https://twitter.com/skwee357) if you have any questions.


Validating Requests With a Simple Middleware for Express


*Русская версия на* [*Хабре*](http://habrahabr.ru/post/266407/)*. Перевод не мой, спасибо* [*webMarshal*](http://habrahabr.ru/users/webMarshal/)*-у за перевод.*

If you have any questions, or want to discuss some points — leave a comment here, or [tweet](https://twitter.com/skwee357) me.

If we take a look at React component we can outline some properties.

# State

Yes, each react component has state. State is something internal to the component. Only the component it self can read and write into its own state and as the name implies, the state of the component is used to store state (captain obvious here). Not interesting. Let’s move next.

# Props

Or shall we say properties. Props is the data that affects the component display and behavior. Props can be optional or mandatory, and they are provided by the **parent** component. Ideally, when you provide your component with the same props — it renders the same. Not interesting as well. Let’s move on.

# Context

Meet context, the reason I’m writing this post. Context is an undocumented feature of react.js and it is similar in a way to props, but the only difference is that props are passed explicitly by parent to child, and they do not propagate down the hierarchy, while context can be requested by children component implicitly.

## But why?

Good question. Lets draw!

![React state props tree {363x313}](/images/react-state-props-tree.png#center)

We have a Grandparent component that renders Parent A component that renders two child components: Child A and Child B.

Lets say Grandparent component knows something that Child A and Child B wants to know as well, but Parent A doesn’t care about. Lets call this piece of data *Xdata.* How would Grandparent component give ChildA and ChildB access to *Xdata*?

Well, using Flux architecture we can store *Xdata* inside a store and let Grandparent, Child A and Child B subscribe to that store. But what if we want Child A and Child B to be *pure dumb components* that only renders some markup?

Well, we than can pass *Xdata* as prop to Child A and Child B. But Grandparent can not pass props to its grand children without going through Parent. And its not that big deal if we have only 3 level nesting, but real applications have a lot more nesting levels where top components acts as containers and leaf components are just markup. Well, we can use mixins that will automatically pass the props down the hierarchy for us, but its not elegant.

Or we can use context. As I said earlier, context allows children component to request some data to arrive from component that is located higher in the hierarchy.

Here is how it looks:

```js
var Grandparent = React.createClass({  
  childContextTypes: {
    name: React.PropTypes.string.isRequired
  },  getChildContext: function() {
    return {name: 'Jim'};
  },
  
  render: function() {
    return <Parent/>;
  }
    
});

var Parent = React.createClass({
 render: function() {
   return <Child/>;
 }
});

var Child = React.createClass({
 contextTypes: {
   name: React.PropTypes.string.isRequired
 }, render: function() {
  return <div>My name is {this.context.name}</div>;
 }
});

React.render(<Grandparent/>, document.body);
```

And here is a [JSBin with the code](https://jsbin.com/yajobivuze/edit?js,output). Change *Jim* to *Jack* and you see how your component re-renders.

## WHAT IS HAPPENING?!

Our Grandparent component says two things:

1. *I provide my children with context type named name of type string.* This is what happening in *childContextTypes* declaration.
2. *The value of context type named name is Jim.* This is what happening in *getChildContext* function.

And our child component just says “Hey I expect to have context type named *name*!” and it gets it. As far as I understand (and I’m far from being expert in react.js internals) when react renders children components it checks which components want to have context and those that want context are provided with context if parent supplies them.

## Cool!

Yep, expect when you encounter the following error

```
Warning: Failed Context Types: Required context `name` was not specified in `Child`. Check the render method of `Parent`.
runner-3.34.3.min.js:1

Warning: owner-based and parent-based contexts differ (values: `undefined` vs `Jim`) for key (name) while mounting Child (see: http://fb.me/react-context-by-parent)
```

Yes of course I checked the link, its not very helpful.

Here is the code that causes this ([JSBin](https://jsbin.com/doqeyasako/edit?js,output)):

```jsx
var App = React.createClass({
  render: function() {
    return (
      <Grandparent>
        <Parent>
          <Child/>
        </Parent>
      </Grandparent>
    );
  }
});

var Grandparent = React.createClass({  
  childContextTypes: {
    name: React.PropTypes.string.isRequired
  },  getChildContext: function() {
    return {name: 'Jim'};
  },
  
  render: function() {
    return this.props.children;
  }
    
});

var Parent = React.createClass({
  render: function() {
    return this.props.children;
  }
});

var Child = React.createClass({
  contextTypes: {
    name: React.PropTypes.string.isRequired
  },  render: function() {
    return <div>My name is {this.context.name}</div>;
  }
});

React.render(<App/>, document.body);
```

*It doesn’t make sense now, but Ill explain a setup where this is a viable hierarchy in the end of this post.*

So what is happening?

It took me a lot of time to understand why this happens. Googling the error only brought me to discussions by people who also wonders why this happens. I looked at other projects like react-router or react-redux that uses context to pass data down the component tree, when eventually I realized what is wrong.

*Note: I said I’m not expert in react internals, so everything I’m going to say now is purely what I understood about react internals. Leave a comment if you think I’m wrong (preferably with a link that backups your comment).*

Remember I said that each react component have *state*, *props* and *context*? Well, each component have as well so called *parent* and *owner*. And if we follow the link from the earlier warning (so yes, it is useful, I lied) we can understand that:

> In short, the owner of a component is whomever creates the component, while the parent of a component is whomever would be the containing ancestor in the DOM hierarchy.

It took me some time to understand this statement.

So in my first example, the owner of Child component is Parent, as well as the parent of Child is Parent. While in the second example the owner of Child component is App while the parent is Parent.

Context is something that propagates in a strange way to all the descendant components, but will be assigned only to those components who explicitly asked for context. But context does not propagate from the parent component as you’d expect but from owner! And since the owner of Child is App, React tries to find the “name” attribute in context of App instead of Parent or Grandparent.

[Here is the relevant bug report in React](https://github.com/facebook/react/issues/2112). And here is the relevant [pull request](https://github.com/facebook/react/pull/3615) that should fix this to Parent based context as opposed to Owner based context in React 0.14.

However React 0.14 is not there yet, so here is a fix ([JSBin](https://jsbin.com/yujihowuwe/edit?js,output)):

```jsx
var App = React.createClass({
  render: function() {
    return (
      <Grandparent>
        { function() {
          return (<Parent>
            <Child/>
          </Parent>)
        }}
      </Grandparent>
    );
  }
});

var Grandparent = React.createClass({  
  childContextTypes: {
    name: React.PropTypes.string.isRequired
  },  getChildContext: function() {
    return {name: 'Jack'};
  },
  
  render: function() {
    var children = this.props.children;
    children = children();
    return children;
  }
    
});

var Parent = React.createClass({
  render: function() {
    return this.props.children;
  }
});

var Child = React.createClass({
  contextTypes: {
    name: React.PropTypes.string.isRequired
  },  render: function() {
    return <div>My name is {this.context.name}</div>;
  }
});

React.render(<App/>, document.body);
```

Instead of instancing the Parent and Child components inside App, we return a function. Then inside the Grandparent we call this function hence making Grandparent the owner of Parent and Child components. Context propagates as expected now.

# Ok, cool, but… WHY?!

Remember [my previous](/a-different-approach-for-localizing-react-js-app) post about localization in react.js? Consider the following hierarchy:

```jsx
<Application locale="en">
  <Dashboard>
    <SalesWidget>
      <LocalizedMoney currency="USD">3133.7</LocalizedMoney>
    </SalesWidget>
  </Dashboard>
</Application>
```

*This is a static hierarchy, but usually you will have some routing and eventually you will create a situation where the owner and parent of your leaf components — differs.*

Application is responsible for loading the locale data and initializing an instance of jquery/globalize. But it doesn’t use it. You don’t localize your top level components. Localization affects usually leaf components like localized text nodes, numbers, money display or time. And I’ve discussed earlier about the 3 possible ways to pass the globalize instance down the tree. Either we store it in a store and let leaf components subscribe to the store, but I think its incorrect. Leaf components should be pure dumb components.

Passing the globalize instance as props can be tedious, imagine ALL your components requires globalize instance. Its the same as making globalize instance a global variable and let those who needs it — use it.

But the most elegant way is using context. Application components says “Hey I have a globalize instance here, anyone who needs it let me know” and any Localized leaf components yells “Me! Me! I want it!”. This is an elegant solution. Leaf components stays pure, they dont depend on stores (yes they depend on context, but they have to, because they need it to render correctly). Globalize instance is not getting passed as props to your entire hierarchy. Every body is happy.

***

That’s it my friends!

May the force be with you.

The land of undocument react.js: The Context


Howdy!

I’ve heard you use ReactJS? Good! I also heard you want to localize your application? That’s great! Well proper localization is hard, there are many js libraries for client side localization as well as [yahoo/react-intl](https://github.com/yahoo/react-intl) that provides localized react components based on JavaScript Intl API.



I my self use es6 syntax and avoid using mixins, because [mixins are dead](https://medium.com/@dan_abramov/mixins-are-dead-long-live-higher-order-components-94a0d2f9e750) (and well, because there is no easy way to integrate mixins into es6 syntax). So react-intl didn’t work for me. But damn I wanted those localized numbers! In this article I’m gonna show a different (not bad neither good, just different) approach on how I did it.

## Localize all the things!!

![Localize all the things!! {400x400}](/images/localize-meme.jpeg#center)

I do like the idea of Intl API, why reinvent the wheel when we have [51M of compressed localized data](http://www.unicode.org/Public/cldr/26/) with support for dates, numbers, currencies and messages. So we do have [jquery/globalize](https://github.com/jquery/globalize) on client side to use all this data. The question is: How do I use it in a react.js application?

Well, here is the general idea

1. We need a way to identify user locale. Either we can guess it from the browser or (a preferred method, in my opinion) let the user choose his locale.
2. Once we know the locale, we need to load the needed cldr json data (we can load everything, or just the parts we really need) into Globalize.
3. ….
4. PROFIT!!!!

Simple. Yet a bit complicated.

One thing I disliked in react-intl is that each component knew about the locale data. If you have a nested tree of: App => Dashboard => SalesWidget => FormattedMoney, even though the locale data is needed only in FormattedMoney component, its passed to all the child components of App (react-intl handled that automatically using mixins). I offer a different solution. Locale data is no more than just… data! And data should be stored inside… yes right a Store!

## Show me the code!

*Note: I use* [*alt*](https://github.com/goatslacker/alt) *as my flux implementation. Ideally my locale info should be fetched from the user, but since I do a MVP, I omitted this step.*

Application component issues a UserFetch action that goes to the API and fetches the user details. Locale store listen to UserFetchCompleted action and then gets the locale from the user, and loads the needed cldr data.

Here is how it looks

```javascript
handleSetupStarted() {
    this.waitFor(ProfileStore.dispatchToken);

    let locale = 'en', //@TODO get from profile
        self = this;
    request({url: CLDR_URL + 'supplemental.json', type: 'json'})
        .then(function (supplemental) {
            request({url: CLDR_URL + locale + '.json', type: 'json'})
                .then(function (localeData) {
                    self.handleSetupFinished(locale, supplemental, localeData);
                })
                .fail(self.handleSetupFailed);
        })
        .fail(self.handleSetupFailed);
}

handleSetupFinished(locale, supplemental, localeData) {
    Globalize.load(supplemental, localeData);
    this.setState({translator: Globalize(locale)});
}
```

(Yes, I know, I do an ajax call from the store. I couldn’t find a better way to do it. For some reason I wans’t able to dispatch an action inside the ProfileStore once the user data loaded because I got this weird message of: *Dispatch.dispatch(…): Cannot dispatch in the middle of a dispatch.* and was lazy to investigate on how to fix it. Ideally this should be inside an action or an alt term called source. I’ll figure it out later).

See, the handleSetupStarted waits for the ProfileStore to finish loading the user, and once its done, we get its locale and load 2 files: supplemental.json (which is a common set of data for every locale) and en.json (which is data related to the en locale). Once it finished loading, it creates a new instance of Globalize.

Here is an example of a LocalizedMoney component

```jsx
class Money extends React.Component {
    constructor(props) {
        super(props);
        this.state = {
            locale: LocaleStore.getState()
        }
    }

    render() {
        let amount = parseFloat(this.props.children),
            translator = this.state.locale.translator,
            cls = classNames({
                money: true,
                positive: amount >= 0,
                negative: amount < 0
            });

        return (
            <div className={cls}>
                {translator.formatCurrency(amount, this.props.currency)}
            </div>
        );
    }
}
```

And a usage example

```jsx
render() {
    return (
        <FormattedMoney currency="USD">1337.93</FormattedMoney>
    );
}
```

See! No need to pass the locale data from the Application component to the LocalizedMoney component! LocalizedMoney just uses the Locale Store. You can even setup listener on localized components, to listen to changes on the Locale store, and when the user fires a Change Locale Action, you can change the locale on the fly without reloading the page. But I wouldn’t mind reloading the page. Locale is not something you change twenty times a day.

You can as well implement caching for different formatters inside the LocaleStore as well, and instead of using the translator (which is just an instance of Globalize) directly, you can use something like

```js
LocaleStore.getCurrencyFormatter(“USD”).format(123.45);
```

Which internally looks like (pseudo code):

```js
getCurrencyFormatter(currencyCode) {
    if(!this.state.currencyFormatters[currencyCode]) {
        this.state.currencyFormatters[currencyCode] = this.state.translator.currencyFormatter(currencyCode);
    }
    return this.state.currencyFormatters[currencyCode];
}
```

*Note: formatter identified not only by currency, but by options as well. You can have two USD formatters: One that shows the number as*

```
$1,000.00
```

*And another one as*

```
1,000.00 US Dollars
```

*In short: RTFM.*

## A note about CLDR shipping

The process of shipping the locale data should be a build step of your application. There is [cldr-data-downloader](https://www.npmjs.com/package/cldr-data-downloader). Its a node module to download the CLDR data from unicode.org.

I then use gulp to bundle the supplemental (common) and locale based data into merged json file.

Less talk, more code:

```js
gulp.task('cldr:download', function (cb) {
    cldrDataDownloader('http://www.unicode.org/Public/cldr/' + CLDR_VERSION + '/json.zip', cldrPath, function (err) {
        if (err) return cb(err);
        cb();
    });
});

gulp.task('cldr:bundle:supplemental', function () {
    var files = ['likelySubtags.json', 'currencyData.json', 'numberingSystems.json', 'plurals.json', 'ordinals.json'];
    return gulp
        .src(files.map(function (f) {
            return path.join(cldrPath, 'supplemental', f);
        }))
        .pipe(extend('supplemental.json'))
        .pipe(gulp.dest(path.join(distDir, 'cldr')));
});

gulp.task('cldr:bundle:locale', function () {
    var files = ['currencies.json', 'numbers.json'];

    var tasks = locales.map(function (locale) {
        return gulp
            .src(files.map(function (f) {
                return path.join(cldrPath, 'main', locale, f);
            }))
            .pipe(extend(locale + '.json'))
            .pipe(gulp.dest(path.join(distDir, 'cldr')));
    });
    return gulpMerge(tasks);
});
```

At this point I need only currency formatting, so I use the required files in both supplemental bundle and locale bundle. [jquery/globalize](https://github.com/jquery/globalize#requirements) actually giving a nice table that shows, what json files from the cldr you need in order to use different localization modules.

## A final note

For now I am happy with this approach. In my opinion it decouples the components from the actual localization implementation. Components stays reusable even if you decide to switch to a different localization implementation. Your store can expose an API like the *getCurrencyFormatter()* I showed earlier, and actual implementation can be based on Intl, or your own. FormattedMoney component doesn’t care.

Intl API is [supported in all major browsers](http://caniuse.com/#search=Intl) and those that do not support it, can be [polyfilled](https://github.com/andyearnshaw/Intl.js/). Of course Intl API can be an overkill for most applications, especially if all you want is translating strings. But if your application requires displaying localized numbers, dates, times — I think there is no better solution other than Intl API.

Best of luck and may the force be with you.


Dmitry Kudryavtsev

Senior Software Engineer / Tech Lead / Consultant

Latest Posts

Validating Requests With a Simple Middleware for Express

The land of undocument react.js: The Context

A different approach for localizing react.js app