Skip to content

Latest commit

 

History

History
217 lines (174 loc) · 8.22 KB

README.md

File metadata and controls

217 lines (174 loc) · 8.22 KB
Raw

API

Hey, welcome to this super awesome API. It has one endpoint! Here is an example request:

curl https://whatsinstandard.com/api/v6/standard.json

This will return something like:

{
  "deprecated": false,
  "sets": [
    {
      "name": "Kaladesh",
      "codename": "Lock",
      "code": "KLD",
      "symbol": {
        "common": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=C&set=KLD",
        "uncommon": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=U&set=KLD",
        "rare": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=R&set=KLD",
        "mythicRare": "http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&size=large&rarity=M&set=KLD"
      },
      "enterDate": {
        "exact": "2016-09-30T00:00:00.000"
      },
      "exitDate": {
        "exact": "2018-10-05T00:00:00.000",
        "rough": "Q4 2018"
      }
    },
    ...
  ],
  "bans": [
    {
      "cardName": "Rampaging Ferocidon",
      "cardImageUrl": "https://img.scryfall.com/cards/large/en/xln/154.jpg?1527429722",
      "setCode": "XLN",
      "reason": "Banned for being too effective a shutdown against counters to aggressive red (filling the board with small creatures and gaining life).",
      "announcementUrl": "https://magic.wizards.com/en/articles/archive/news/january-15-2018-banned-and-restricted-announcement-2018-01-15"
    },
    ...
  ]
}

But you can just visit it yourself to see everything. You'll get some JSON containing an array of Magic sets and banned cards.

Documentation

The API specification is written in JSON Schema, which is a way of saying programmatically what the structure of the API is. You can view the user-friendly documentation generated by the schema using this link:

View documentation

You can also view or download the raw JSON Schema to help you validate your code or generate structures in your language of choice automatically.

Notes

The sets array contains a superset of all sets in Standard -- it may contain some sets that have dropped and some sets that have not yet released. It is your responsibility to filter these sets out by comparing each set's enter_date and exit_date to the current date.

Here's a JavaScript function that does just that:

const standardSets = (callback) => {
  fetch("https://whatsinstandard.com/api/v6/standard.json").then((response) =>
    response.json().then((body) => {
      callback(
        body.sets.filter((set) => {
          return (
            (Date.parse(set.enterDate.exact) || Infinity) <= Date.now() &&
            (Date.parse(set.exitDate.exact) || Infinity) > Date.now()
          );
        })
      );
    })
  );
};

The bans array is in order of ban, from oldest ban to newest. Again, it contains a superset of all bans in Standard -- it may contain some bans that belong to sets that have dropped. Filter these bans out by correlating each ban's setCode to a code from a set included in the sets array, filtered to exclude non-Standard sets:

const bannedCards = (callback) => {
  fetch("https://whatsinstandard.com/api/v6/standard.json").then((response) =>
    response.json().then((body) => {
      callback(
        body.bans.filter((ban) => {
          return body.sets
            .filter((set) => {
              return (
                (Date.parse(set.enterDate.exact) || Infinity) <= Date.now() &&
                (Date.parse(set.exitDate.exact) || Infinity) > Date.now()
              );
            })
            .map((set) => set.code)
            .includes(ban.setCode);
        })
      );
    })
  );
};

Automatic deprecation alerts

When using the API, you should always check the root object's boolean field deprecated, which will flip on if that API version becomes deprecated. Configure your program to notify you if this field is ever true so you aren't caught off guard if the version you use is deprecated then eventually killed.

API v1 through v4 are past deprecation and no longer available.

Changelog

Version 6

  • All properties that used snake_case now use camelCase.
  • enterDate, roughEnterDate, exitDate, and roughExitDate have been simplified to enterDate and exitDate, each an object with rough and exact properties.
  • (enter|exit)Date.rough can now hold either a month or a quarter.
  • code can now be null.
  • name can now be null.
  • Added codename property.
  • Set symbols are once again available in the API.
  • The block property has been removed.
Midversion nonbreaking changes
  • 2023-02-19: The description for the date.exact field in the schema definition (manifested as sets[].enterDate.exact and sets[].exitDate.exact) has updated from promising RFC 3339 to promising ISO 8601. No behavior has changed; this only brings the field's description in line with its behavior. See #255.

Version 5

  • The root element in the response is now an object, not an array. The root object's sets field is the array.
  • Added a new deprecated field to the root object. This field will be false until v6 of the API is introduced, which will flip it to true.
  • The API base path has changed from whatsinstandard.com/api/\d to whatsinstandard.com/api/v\d to be more consistent with the rest of the internet.
  • Like upcoming sets in v4, sets that have rotated out of Standard can now be included in the sets array. There is no guarantee about the number of these sets included (though it will generally be single-digit). You should filter on enter_date and exit_date if you care only about the sets currently in Standard.
  • enter_date can now be null to allow for upcoming sets whose release dates are not known.
  • block can now be null to allow for new blockless sets.
Midversion nonbreaking changes
  • 2018-04-28: enter_date and exit_date no longer include timezone (see #75). The dates are still ISO 8601 compatible and are now intended to be parsed in the local timezone.
  • 2019-02-28: Documentation for code now correctly states it matches /[A-Z0-9]{3}/. It previously incorrectly stated that it matched /[A-Z]{3}/. No behavior has changed, only documentation.
  • 2019-02-28: Banned cards are now included in API.

Version 4

  • Upcoming sets are once again included in the sets array. To use only released sets or only unreleased sets, filter on enter_date.
  • block can no longer be null, as no more core sets will enter Standard.
  • The symbol field has been removed to decrease maintenance work. If you'd like still like to fetch set images, you can instead use the code field to construct an image URL like http://gatherer.wizards.com/Handlers/Image.ashx?type=symbol&set=<code>&size=large&rarity=C.
  • rough_exit_date regex has changed from /(early\/mid|late) 20\d\d/ to /Q\d 20\d\d/ for simplicity.

Version 3

Valid rough_exit_date regex has changed from /(early|late) 20\d\d/ to /(early\/mid|late) 20\d\d/ to account for the new Standard rotation style. Old API versions will continue to match their respective regexes, but with potentially less accuracy. See Wizards's article on the change for details.

Version 2

Upcoming unreleased sets are no longer included in the sets array.

Contributing

If you're making changes to the API, note that the api/v*/*.json files are generated programmatically by api/v*/generate.js scripts. The scripts read the unstable api/internal.json file in this directory and output version-stable JSON.

In other words: api/internal.json is the database, api/v*/generate.js is the view, and api/v*/*.json is the generated output.

Run

npm install

to regenerate the endpoints.