zanata/zanata-spa — pull request #24 by davidmason (2014-09-05 00:04:01+00:00)
Title: Add URLs for translation states and text flow data

Adds 2 URLs to UrlService, and adds another helper function for building up REST URLs.

I am unsure which approach is better for describing a set of URLs: defining a URL and extending it or defining each URL in full.

Defining each in full can be fairly readable if they are manually aligned:

```
var projectUrl = restUrl('/projects/p/:projectSlug'),
versionUrl = restUrl('/projects/p/:projectSlug/iterations/i/:versionSlug'),
documentsUrl = restUrl('/projects/p/:projectSlug/iterations/i/:versionSlug/r'),
documentUrl = restUrl('/projects/p/:projectSlug/iterations/i/:versionSlug/r/:docId'),
statesUrl = restUrl('/projects/p/:projectSlug/iterations/i/:versionSlug/r/:docId/states/:localeId');
```

but they get much harder to read if the alignment is out by one or two characters, particularly once you start defining several endpoints that branch from the same base.

Extending endpoints can be much more concise, and captures the essential information for an endpoint, but makes it a bit more work to figure out the full URL structure. The main reason to look at the full URL structure is to figure out which properties must be defined when using the URL, such as `:projectSlug` and `:versionSlug` for `versionUrl`.

```
var projectUrl = restUrl('/projects/p/:projectSlug'),
versionUrl = extendRestUrl(projectUrl, '/iterations/i/:versionSlug'),
documentsUrl = extendRestUrl(versionUrl, '/r'),
documentUrl = extendRestUrl(documentsUrl, '/:docId'),
statesUrl = extendRestUrl(documentUrl, '/states/:localeId');
```

A third approach that doesn't seem as good as either of the others is to compose parts of each URL. This would work right now because the functions I defined to create and extend URLs are variadic:

```
var projectPart = '/projects/p/:projectSlug',
versionPart = '/iterations/i/:versionSlug',
documentsPart = '/r',
documentPart = '/:docId',
statesPart = '/states/:localeId';

var projectUrl = restUrl(projectPart),
versionUrl = restUrl(projectPart, versionPart),
documentsUrl = restUrl(projectPart, versionPart, documentsPart),
documentUrl = restUrl(projectPart, versionPart, documentsPart, documentPart),
statesUrl = restUrl(projectPart, versionPart, documentsPart, documentPart, statesPart);
```
It might make it a little easier to see which parts a URL is made up of, but it has as much repetition as just writing out each one, without the ability to see the placeholders in-place.