Search code examples
apiblueprint

Documenting Mutually Exclusive Query Parameters in API Blueprint

I'm documenting a public API that has a method named /findGuild that takes a mandatory key parameter and one of the following parameters:

  1. byPlayer
  2. byName

It must have either byPlayer or byName; My question is: How do I indicate that byPlayer and byName are mutually exclusive, but one is mandatory?

Right now, I have the following in my .apib for this Resource:

### GET /findGuild{?byName,byPlayer,key}

+ Parameters
  + byName: `YourGuild` (string, optional) - Search for the Guild by its name.
  + byPlayer: (string, optional) -  Search for Guild by a player. Does not seem to work.
  + key: `ffffffff-ffff-ffff-ffff-ffffffffffff` (string, required) - The user's API key.

+ Response 200 (application/json)

    + Attributes (object)
      + guild (string) - The guild id or null.
      + success (boolean) - Should be true.

    + Body

            {
              "guild": "ffffffffffffffffffffffff",
              "success": true
            }
Solution

  • I am afraid (but not totally sure) API Blueprint is not capable of expressing this kind of relationship at the moment.

    What I can surely tell you is that, according to public roadmap, URI Parameters will be replaced with an MSON object, which supports the scenario you're asking for.

    Hope it helps!