LoCulator Documentation

Short and sweet - I promise!

Public projects

GET https://loculator.singularity.net.za/api/loc/gitlab.com/ koel/loculator

Typical response: 200

    "vcs_url": "https://gitlab.com/koel/loculator",
    "cached_commit": "484ea7d431637d5d374e8261d59f222fc7cfd3e4",
        "total_lines": 249,
        "blank_lines": 58,
        "total_files": 6,
        "non_text_files": 0

The API also works with Bitbucket, Github, and custom git providers (like self-hosted Gitlab). Simply replace gitlab.com in the URL with your provider's domain.

For sake of caching, on every request the latest commit hash is fetched through the relevant VCS provider's public API. If there's a cache miss, the app will respond with status 202 (Accepted), meaning the lines will be counted in the background. The latest cache at that point will also be returned, if present.

If you (the caller) happen to know the latest commit hash, you can speed up the cache check by passing it in in the latest_commit URL parameter:

GET https://loculator.singularity.net.za/api/loc/gitlab.com/ koel/loculator? latest_commit=1709cf9e42d91bf14d958f8a4a4c7d24f2170e2c

Calls to the same endpoint after receiving status 202 will instantly return the same results, so long as the counting job is running (or queued). Exponential backoff is recommended for checking if counting is complete. A 200 response means the data is the latest.

Private projects

To allow LoCulator to clone private repos, you should add its public SSH key with read-only permissions to your VCS account. Guides to do this: GitHub, BitBucket, and GitLab.

Then when you make a request, add the private parameter. This will force SSH.

GET https://loculator.singularity.net.za/api/loc/github.com/ someone/somerepo? private=true

Note that there's no auto caching for private repos. You're welcome to make a PR if you want this feature!
For now, the app will always trust what you specify as the latest commit hash for private repos. If omitted, the cache will be returned and no job will be queued.


Service built by George Rautenbach