Skip to content

Commit

Permalink
Merge pull request #8 from apiaryio/zdne/example
Browse files Browse the repository at this point in the history
They say example goes a long way...
  • Loading branch information
smizell committed Mar 2, 2016
2 parents 6c5e4a7 + eba72f7 commit 0e2d5c9
Showing 1 changed file with 15 additions and 0 deletions.
15 changes: 15 additions & 0 deletions docs/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,21 @@ Additional examples are provided throughout this documentation for specific API

As mentioned, for consumers, it is important to not couple code to the specific structure of an API Elements document. The common pitfall is to reference elements by specifying a specific and strict path to those elements, but it is recommended to try to avoid this for sake of evolvability and safety.

For example, to get the first HTTP Transaction element from an API Elements tree.

Relying on a fixed tree structure:

```js
const transaction = apielements.content[0].content[0].content[0].content[0].content[0]
```

Querying the tree in a way that does not use a strict path:

```js
import query from 'refract-query';
const transaction = query(apielements, {element: 'httpTransaction'})[0];
```

Given that API Elements use [Refract][], the structure of the document is recursive by nature. When looking for specific elements, it is best then to walk the tree to look for a match. Querying the tree means that your code will be decoupled not only from specific API description documents, but it will also be decoupled from the structure of those documents.

[Refract]: https://github.com/refractproject/refract-spec/blob/master/refract-spec.md
Expand Down

0 comments on commit 0e2d5c9

Please sign in to comment.