Use the API

 

If you're here, you're probably aware that an API is an Application Programming Interface, or a way for one software application to talk to another. If that's news to you, this guide may be a hard slog, but you might still be interested in checking out labs.wikirate.org to see some of the cool things being developed by Wikirate's community of API users.

A little context

Wikirate's API, like its underlying data structure, is a little unconventional. But if you understand why and how the structure is unusual, the API design will make sense. So let's start there.

First, Wikirate is, as it's name implies, a wiki. It is built with an open-sourced wiki platform called Decko, which uses wiki-inspired building blocks called cards to create complex web systems. Pretty much everything you interact with on Wikirate is a card: Companies, Metrics, Answers, Projects, Data Sets, Topics, etc. –– they're all cards. What's particularly unusual is that the substructures of these pages are cards, too. The logo of a company, the formula of a metric, the topic tags on a data set... it's cards all the way down.

The embrace of this wiki card concept helps Wikirate live up to its values of transparency. Since everything is a card, and every card stored has a revertible revision history, the Wikirate platform is deeply transparent, and it exposes not just current data but also data histories to its API.

Card marks

The API docs make frequent references to marks. "Mark" is our general term for any of the ways for uniquely identifying cards.

Names

Every card on Wikirate, across all types, has a unique name. You cannot, for example, have a project and a company with the same name. This helps Wikirate adhere to an old wiki principle that you should be able to link to any content knowing only its name, and (as we will see) it also makes for very user-friendly urls. This, too, applies to nested cards, which are typically organized using structured names. For example, the logo on a company card is the name of the card plus "image".  Here, for example, is the "Apple Inc+image" card:

While the standard form of a card's name retains punctuation and capitalization, these things are stripped in the key that governs Wikirate's namespace.  So "Apple Inc", "apple inc", "APPLE INC", and "Apple@#$#$%INC" all refer to the same card (which has the default form of "Apple Inc.").

Ids

Every real card on Wikirate also has a unique numerical ID. These IDs are seldom seen in the UI but can easily be exposed by adding "/id" (or, for a text response, "/id.txt" or "/id.json") to a standard card url.

• wikirate.org/Apple_Inc/id.txt
• wikirate.org/Apple_Inc+image/id.txt

The above shows that Apple Inc, and Apple Inc+image are indeed two different cards with different ids.  Now that we have figured out their ids, we can use the id in place of the name in any request by preceding the id with a tilde, eg:

• wikirate.org/~1578
• wikirate.org/Apple_Inc

Those two links are functionally equivalent. But note that IDs are more permanent than names; if a card's name is edited, its ID remains the same. So a best practice for coders using the API is to use friendly variable names for companies (or metrics or data sets or company groups or whatever else) to hold IDs for use in API calls.

Wait, back up. What do you mean every "real" card has an id? Some cards aren't real??

Indeed, some patterned cards are virtual, meaning that they aren't actually stored in the database. Instead, they are dynamically constructed on the fly using rules. Here are some examples:

Codenames

You may sometimes encounter a third identifier, the "codename".  Most cards don't have these, only cards that are referred to directly in code. These permanent identifiers are more developer friendly than IDs, and unlike IDs they are constant across different Decko sites that share the same code. To use a codename in a request, preface it with a colon (:).

Formats and views

Since Wikirate's data is structured around a single namespace, so is its API. Whereas most APIs have different endpoints for different datatypes, all Wikirate data is in cards, so we focus on a single card endpoint with many formats and views.

Formats

Wikirate's API provides data views in HTML, JSON, CSV, TXT, and other formats. Because images are also cards, image formats like PNG, JPEG, and SVG follow the same patterns.  In all cases, you can use any one of the following three methods to specify the format:

1. via filename extension, eg  GET /cardname.json
2. via query variable, eg GET /cardname?format=json
3. via http access header, eg Accept: application/json

Views

For any card on Wikirate, it's possible to add ".json" to its name to see a default JSON view for that card, but there are also many other views available. In the "Card marks" section above, we demonstrated on very simple view: id. There are two ways to specify a view:

1. in the path as /CARD_MARK/VIEW, eg GET /Apple_Inc/id
2. in the query as /CARD_MARK?view=VIEW, eg GET Apple_Inc?view=id

Sorting and filtering

If you've explored Wikirate's UI, you've likely noticed the prominent sorting and filtering features. All of this functionality is available via the API. And in fact, one handy pattern when you're getting started with Wikirate's API is to being by using the UI, and then to click on the JSON export link below the results.

Specific sorting and filtering parameters are documented in the SwaggerHub docs.

Authentication and authorization

Wikirate data is and always will be free and open. There are, however, more restrictions on API usage for unauthenticated users. For example, many answer searches will return up to 5000 results for authenticated users but only 500 for anonymous users. Moving forward, the relative benefits to authenticated users will only increase, so it's generally well worth your while to sign up for a free account and authenticate.

To authenticate you will need an API key, which you can generate from your profile page. To get there, click your username on the right side of the nav bar at the top of the page, go to the accounts tab, and click "Generate Key"

Once you have your API Key, you can use it to authenticate in one of two ways: directly or via JWTs.

The advantage of using the API Key directly in your requests is that it's a little quicker to get started. The disadvantages are that it's less secure and a little bit slower.

For faster and more secure requests, you can use JavaScript Web Tokens, or JWTs. JWTs faster because, unlike API keys, they don't require lookups; all the login information is encoded in the token itself. And they're more secure because they are temporary and expire after a fixed amount of time (in Wikirate's case, two hours).

If you have generated an API Key, then you will see text below your key that includes a link to generate a JWT. You can use the link directly or call it via the API. (The best practice pattern is to use your API key to retrieve a JWT and then authenticate with that JWT until it expires).

Python, Java & Ruby API Wrappers

API wrappers are available in Python, Java and Ruby thanks to NLnet’s support. They are easy to install, and they make it easy to get rolling with Wikirate API calls. All three wrappers are open-source and available on GitHub, where anyone can contribute, give feedback, and request changes.

Each wrapper has detailed documentation, and all necessary links to additional resources are provided in the README file on each repository, along with details on how you can contribute and give feedback:
GitHub Repositories:

• Java Wrapper: wikirate4j
• Python Wrapper: wikirate4py
• Ruby: wikirate4ruby

Wikirate Labs

Folks are building cooler and cooler things with Wikirate's API. At labs.wikirate.org we're gathering the best experiments and making them easy to explore, study, and extend.

---