Links

Link database.

The link database is a database whose items are URIs (and associated meta data) to resources available on the web. The purpose of this database is to centralize the mapping of URIs to canonical identifiers which should be used throughout the project. By having a single set of canonical identifiers, we are able to perform URI transformations in source files (e.g., URL shortening via a third party service for tracking and monitoring) and to provide internal project tooling for searching, managing, maintaining, and using URIs.

By way of example, suppose two Markdown documentation files want to reference a resource describing regular expressions in JavaScript. One file uses the identifier mdn-regexp, while the other file uses the identifier js-regexp. At some later point, we decide that we want to refer to a single resource (e.g., https://example.com), different from the one previously used. Because we have used different identifiers, we cannot do a simple find and replace based on identifier.

Extending our example, further suppose that md-regexp and js-regexp point to two different URIs. At some later point, we want them to reference the same resource. Not only can we not find and replace based on identifier, we cannot find and replace based on URI.

If we extend this example to many files across the entire project, we see that allowing each documentation file to maintain its own conventions and URIs is neither maintainable nor scalable. By centralizing link management, we apply a top-down approach to ensure consistency and maintainability across the project, which is particularly important once we want to track which URIs are accessed and when.

Usage

The database is a JSON file, where each key is a URL specifying the location of a resource accessible via the web and each value is an object containing the resource id and other meta information.

{
    ...
    "http://www.json.org/": {
        "id": "json",
        "description": "...",
        ...
    },
    ....
}

Notes

• Before adding a database entry, ensure that the resource is unique and not already present in the database.
• Before assigning an id to a URL, ensure that the id is unique.
• Ensure that a URL is percent-encoded.