Add URL patterns to README.md

Author: djmitche

README.md

@@ -9,6 +9,8 @@ A simple library to generate URLs for various Taskcluster resources across our v
 This serves as both a simple shim for projects that use JavaScript but also is the reference implementation for
 how we define these paths.
 
+URLs are defined in the 'Taskcluster URL Format' document.
+
 Changelog
 ---------
 View the changelog on the [releases page](https://github.com/taskcluster/taskcluster-lib-urls/releases).

docs/urls-spec.md

@@ -1,25 +1,31 @@
 ---
-title: Specific paths for various Taskcluster resources
+title: Taskcluster URL Format
 order: 10
 ---
 
-A Taskcluster `rootUrl` is a partial web address containing at least the scheme, host, and optionally a port. In addition, it can optionally specify a
-path which will end up being a prefix for all other resources.
+# RootUrl
 
-Examples:
+A Taskcluster `rootUrl` is a partial web address containing at least the scheme, host, and optionally a port. It cannot specify a path.
+
+Example:
 
 ```
 https://taskcluster.example.com
-https://taskcluster.example.com/cluster1
-https://example.com/
-https://example.com/cluster2
 ```
 
-At a given `rootUrl`, the following resources will exist:
+# URLs
+
+Taskcluster uses URLs with the following pattern:
+
+| method | result |
+| --- | --- |
+| api(rootUrl, service, version, path) | `<rootUrl>/api/<service>/<version>/<path>` |
+| apiReference(rootUrl, service, version) | `<rootUrl>/references/<service>/<version>/api.json` |
+| docs(rootUrl, path) | `<rootUrl>/docs/<path>` |
+| exchangeReference(rootUrl, service, version) | `<rootUrl>/references/<service>/<version>/exchanges.json` |
+| schema(rootUrl, service, schema) | `<rootUrl>/schemas/<service>/<schema>` |
+| ui(rootUrl, path) | `<rootUrl>/<path>` |
+
+*NOTE*: you should *always* use this library to generate URLs, rather than
+hard-coding any of the above patterns.
 
-`$rootUrl/<path>`: At the root, the ui will be served.
-`$rootUrl/docs/<path>`: The taskcluster documentation site.
-`$rootUrl/references/<service>/<version>/api.json`: A reference for the api exposed by a service.
-`$rootUrl/references/<service>/<version>/exchanges.json`: A reference for exchanges published by a service.
-`$rootUrl/schemas/<service>/<version>/<schema>`: A schema associated with a service.
-`$rootUrl/api/<service>/<version>/<path>`: All services will be routed to under the prefix of `api` with the service name and version in the path as well.