<commit_before># WunderAPI

WunderAPI is a tool for defining, documenting, and testing an API by simply writing example API calls in a markdown document. It is currently intended only for testing APIs that return JSON, and are described in a Markdown file.

In essence, you write a couple examples in your doc/spec and - *BAM* - wunderapi turns those into executable tests.

## Usage

    wunderapi [API root URI] [testfile1] [testfile2] ...

## Example

If you had the file `example.md`:

    # Todo API

    ## Listing tasks

        GET /tasks/

    Returns an empty list:

        200 OK
        Content-Type: application/json

        []

Executing it like this:

    wunderapi http://api.example.com/v1/ example.md

Would give the output:

    GET /tasks/
    ✓ 200 OK
    ✓ content-type: application/json
    ✓ []
    
    ✓ OK » 3 honored (0.112s)

## Format

The format is simple: You write a markdown file. Any code block that begins something like `VERB /path` will be considered a request, and any code block that begins with a 3-digit numeric code will be considered a response.

### Request format

A request looks like this:

    VERB /path/to/resource
    Request-Header: ...

    POST DATA GOES HERE

The HTTP request will be sent basically as-is, with the exception of `Host` and `Content-Length` headers, which will be calculated automatically.

### Response format

A response looks like this:

    CODE Status Message
    Required-Response-Header: ...

    { "data": "is all JSON-encoded" }

Acceptance criteria:

  * The CODE *must* match the CODE of the response
  * Any header defined *must* appear in the response, but additional headers *may* be returned. The order is free.
  * The data returned will be JSON-decoded and compared with the expected response. The objects must be identical. If no expected response data is given, the response body must be blank.

## Contributing

WunderAPI is licensed under an MIT License. Contributions and bug reports are welcome, please use Github for those purposes.

### License
<commit_msg>Add variables and globs to README<commit_after># WunderAPI

WunderAPI is a tool for defining, documenting, and testing an API by simply writing example API calls in a markdown document. It is currently intended only for testing APIs that return JSON, and are described in a Markdown file.

In essence, you write a couple examples in your doc/spec and - *BAM* - wunderapi turns those into executable tests.

## Usage

    wunderapi [API root URI] [testfile1] [testfile2] ...

## Example

If you had the file `example.md`:

    # Todo API

    ## Listing tasks

        GET /tasks/

    Returns an empty list:

        200 OK
        Content-Type: application/json

        []

Executing it like this:

    wunderapi http://api.example.com/v1/ example.md

Would give the output:

    GET /tasks/
    ✓ 200 OK
    ✓ content-type: application/json
    ✓ []
    
    ✓ OK » 3 honored (0.112s)

## Format

The format is simple: You write a markdown file. Any code block that begins something like `VERB /path` will be considered a request, and any code block that begins with a 3-digit numeric code will be considered a response.

### Request format

A request looks like this:

    VERB /path/to/resource
    Request-Header: ...

    POST DATA GOES HERE

The HTTP request will be sent basically as-is, with the exception of `Host` and `Content-Length` headers, which will be calculated automatically.

### Response format

A response looks like this:

    CODE Status Message
    Required-Response-Header: ...

    { "data": "is all JSON-encoded" }

Acceptance criteria:

  * The CODE *must* match the CODE of the response
  * Any header defined *must* appear in the response, but additional headers *may* be returned. The order is free.
  * The data returned will be JSON-decoded and compared with the expected response. The objects must be identical. If no expected response data is given, the response body must be blank.

## Advanced Format

Sometimes, literally matching the response just isn't powerful enough. For this reason, there are some extra tools that WunderAPI gives you.

### Variables

Any uppercase text enclosed in square brackets (such as `[USER_ID]` or `[AUTH_TOKEN]`) is considered a *variable*. Since WunderAPI is declarative, all instances of a variable must match. Here's an example:

    We post a new status update:

        POST /status/

        { "text": "Hello World" }

    It gets a new ID assigned by the server:

        201 Created

        { "id": [STATUS_ID], "text": "Hello World" }

    Then, when we ask for the status by id

        GET /status/[STATUS_ID]

    We get it back:

        200 OK

        { "id": [STATUS_ID], "text": "Hello World" }

In this example, the `[STATUS_ID]` will get set in the first server response, by simply matching whatever it sees there. This could be an integer, a string, or even an array or an object. From that moment on, the variable is *bound* - it cannot change for any reason. Thus, in the second test, if the `id` field of the response did not match what we got on creation, an error would be found.

Variables may also be captured and inserted into headers:

    We sign in:

        POST /login

        { "email": "<EMAIL>", "password": "<PASSWORD>" }

    And get back an authentication token

        200 OK
        X-Auth-Token: [AUTH]

    Which we can pass back to the server

        GET /secret/resource
        X-Auth-Token: [AUTH]

    to get access to privileged content

        200 OK

        { "privacy": "top_secret", ... }

This last response brings us to our next topic: globs

### Globs

WunderAPI supports two kinds of globs: `*`, which matches any JSON value, and `...`, which matches any set of key-value pairs.

The `*` glob is useful if you care that a value is there, but not what it is. It can be thought of as a variable that does not capture any value. For example, you might write:

    GET /status/1

    200 OK

    { "id": 1, "text": "This entry was inserted previously", "created_at": * }

In this instance, the response value would be required to have an `id` of 1, a `text` of "This entry was inserted previously", and a `created_at` field - however, the `created_at` field could be any value at all: a string, a number, a boolean, even an array or an object. If any of those fields were missing, we would get an error - but we would *also* get an error if any fields were returned that were not shown here.

The `...` glob is useful for just the case where we want to ensure certain fields are set, but there may be other fields we don't care to enumerate. Caution should, however, be exercised - part of the value of WunderAPI specs is that a reader can have a good impression of the full extent of the API, and thus, even if the testing of particular fields is not necessary, being strict will both ensure greater understandability of the markdown *and* additional protection from unforseen consequences if the API changes in any way.

## Contributing

WunderAPI is licensed under an MIT License. Contributions and bug reports are welcome, please use Github for those purposes.

### License

{'fraction_non_alphanumeric': 0.07090020935101186, 'fraction_numerical': 0.006699232379623168, 'mean_word_length': 3.1160252728317057, 'pattern_counts': {'":': 13, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3031382', 'n_tokens_mistral': 2000, 'n_tokens_neox': 1883, 'n_words': 1046}