<commit_before>---
title:  "API Documentation Using Tabular Expressions"
date:   2017-07-20 15:04:23
categories: [api, REST, tabular, documentation]
tags: [api, REST, tabular, documentation]
excerpt_separator: <!--more-->
---
It is wellknown that APIs need developer-friendly docs in order
to gain widespread adoption. However, little if any improvement in the way REST APIs are presented to developers have been made over the 
past few years. Nowadays, most API docs and developer portals adopt a [Swagger UI](http://petstore.swagger.io/) type of format where all the endpoints in the specification
are simply listed, one after another. This format does a good job of communicating the low level details of each endpoint; However, 
as the complexity of APIs grows, developers need a way to get a high level understanding of the API **before** diving down into those
low level details.
<!--more--> 

![swagger example](/images/petstorev2.png)

The image above depicts Swagger UI documentation for a sample pet resource. As an API specification grows in complexity,
I find it increasingly difficult to answer the following questions using the aformentioned format.

1. **What are all the resources that this API exposes?**

This one is pretty explanatory, even with tags, an API specification with many endpoints will take a long time to navigate.

2. ** What operations are available on key resources? **

This questions exists for the same reason as the first question. API specifications with increasing complexity make
it difficult force developers to sift through longer than necessary lists of endpoints to figure out what operations are
avaialable for a given resource.

3. **What relationships exist in the ways these resources are consumed?**

Developer apps seldom depend on a single endpoint or API call from a third party API. Instead, such apps are built
by stringing together numerous API calls on the fly based on certain user scenarios. By helping developers understand
the requirements of and relations between the consumption of resources, you are helping them  
documentation:

### Introducing API Tables

![tabexpr](/images/tabexprv6.svg)

#### Scalability
Many APIs are not as simple as the one presented in the sample above. If you have worked with the APIs provided by
GitHub, Twitter or Facebook to name a few, you'll know that





Solution




Why Its Better


<commit_msg>Update 2017-07-25-API_Tables.md<commit_after>---
title:  "API Documentation Using Tabular Expressions"
date:   2017-07-20 15:04:23
categories: [api, REST, tabular, documentation]
tags: [api, REST, tabular, documentation]
excerpt_separator: <!--more-->
---
It is wellknown that APIs need developer-friendly docs in order
to gain widespread adoption. However, little if any improvement in the way REST APIs are presented to developers have been made over the 
past few years. Nowadays, most API docs and developer portals adopt a [Swagger UI](http://petstore.swagger.io/) type of format where all the endpoints in the specification
are simply listed, one after another. This format does a good job of communicating the low level details of each endpoint; However, 
as the complexity of APIs grows, developers need a way to get a high level understanding of the API **before** diving down into those
low level details.
<!--more--> 

![swagger example](/images/petstorev2.png)

The image above depicts Swagger UI documentation for a sample pet resource. As an API specification grows in complexity,
I find it increasingly difficult to answer the following questions using the aformentioned format.

1. **What are all the resources that this API exposes?**

This one is pretty explanatory, even with tags, an API specification with many endpoints will take a long time to navigate.

2. ** What operations are available on key resources? **

This questions exists for the same reason as the first question. API specifications with increasing complexity make
it difficult force developers to sift through longer than necessary lists of endpoints to figure out what operations are
avaialable for a given resource.

3. **What relationships exist in the ways these resources are consumed?**

Developer apps seldom depend on a single endpoint or API call from a third party API. Instead, such apps are built
by stringing together numerous API calls on the fly based on certain user scenarios. By helping developers understand
the requirements of and relations between the consumption of resources, you are helping them  
documentation:

### Introducing API Tables

![tabexpr](/images/tabexprv7.svg)

#### Scalability
Many APIs are not as simple as the one presented in the sample above. If you have worked with the APIs provided by
GitHub, Twitter or Facebook to name a few, you'll know that





Solution




Why Its Better



{'fraction_non_alphanumeric': 0.053593685085168256, 'fraction_numerical': 0.009555463232239303, 'mean_word_length': 4.560046189376443, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '221304', 'n_tokens_mistral': 1222, 'n_tokens_neox': 1104, 'n_words': 705}