Skip to content

Propose changes to format allowing greater flexibility. #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexcouper wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Propose changes to format allowing greater flexibility. #13

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 47 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ limited to) APIs that exchange JSON data.
Specification
-------------

The main building block of ABE is a JSON file that illustrates one API call.
The main building block of ABE is a JSON file that illustrates an API endpoint.
One API call is an HTTP request that consists of a URL (pattern), sample
request data and sample response data. Additional fields are included for
documentation purposes.
Expand All @@ -42,7 +42,9 @@ The skeleton of an ABE file is:
"request": {
"queryParams": <params>,
"headers": <headers>,
"body": <body>
"body": <body>,
"url": <url>,
"method": <http method>
},
"response": {
"status": <status>,
Expand All @@ -55,14 +57,18 @@ The skeleton of an ABE file is:
```

* `description` is an optional text describing the API or the concrete example
* `url` is a base location for our API.
* `url` is a base location for our API. It is inherited by each example
if declared at the top, but an examples definition (if present) takes
precedence.
* `examples` contains your different API examples for the contract, this can be
in the form of an `array` or an `object`.
* `label` is an arbitrary label that you can use to refer to one concrete
example, useful when you want to include more than one possible responses.
For instance, `"OK"` and `"Not found"`, or `"Empty"` versus `"One"`
versus `"Many"`.
* `http method` is one of the HTTP verbs `GET`, `POST`, `PUT`...
* `http method` is one of the HTTP verbs `GET`, `POST`, `PUT`... It is
inherited by each example if declared at the top, but an examples definition
(if present) takes precedence.
* `params` are query string parameters to add to the URL
* `headers` is an optional object mapping headers to values
* `status` is HTTP status: `200`, `404`, etc...
Expand All @@ -74,14 +80,13 @@ To illustrate with a concrete example:

```json
{
"description": "Retrieve a list of brands",
"description": "A list of brands",
"url": "/campaigns/brands/",
"method": "GET",
"examples": {
"OK": {
"Fetch-OK": {
"description": "Collection found",
"request": {
"url": "/campaigns/brands/",
"queryParams": {},
"body": {}
},
Expand All @@ -106,6 +111,41 @@ To illustrate with a concrete example:
}
]
}
},
"Create-OK": {
"description": "Creation of brands is legit",
"request": {
"method": "POST",
"queryParams": {},
"body": {
"name": "Nike"
}
},
"response": {
"status": 200,
"body": [
{
"id": 1,
"name": "Microsoft"
},
{
"id": 2,
"name": "Monsoon"
},
{
"id": 3,
"name": "Mars"
},
{
"id": 4,
"name": "John Lewis"
},
{
"id": 5,
"name": "Nike"
}
]
}
}
}
}
Expand Down