The Easiest Ways to Generate API Documentation

the-easiest-ways-to-generate-api-documentation

As a developer whether you are a web developer or app developer, you may be familiar enough with API documentation. API documentation is an important part of the product offering affordances to the developer community to help them understand exactly what an API offers and how to use it. Below are several hints that you can use to create API documentation easily:

What API Documentation Should Contain

You can create your own API Documentation as you like, since there are no standards on what API documentation should encompass. The important thing is makes it easy for them to understand an API is a good starting point. However, you can follow the list below from established providers in the API economy:

  • A list of the resources with an explanation of the purpose of each in the context of the product or service being offered via the API;
  • Examples of API calls in a variety of languages and tools (cURL, Postman Collections, etc.);
  • Do something meaningful in the context of the product or service the API offers, guides that detail the workflows implicit in using the API i.e. the sequence of API calls. For example, Dwolla offers several guides on how to send or receive money, with branches into different contexts throughout that explain the different aspects of their product offering;
  • An overview of the design principles adopted by the API provider and what that means for aspects adherence to REST (especially hypermedia), HTTP codes, etc.;
  • Information on authentication, including schemes that may be implemented such as OAuth or OpenID Connect;
  • General information on error handling with information on the HTTP return codes that will be returned;
  • User-specific contexts that help developers get to grips with the subject matter more easily. For example, Stripe automatically tailors their API documentation with your API key and secret (when you are logged in) so any code samples are immediately ready to use;
  • An interactive API explorer that allows the developer to readily bring all this information to life.

Interactive Explorers

It is a common thing to have an Interactive Explorers in API specification formats generated from the specification document itself, creating a means for consumers to both learn about and test API calls at the same time. With the help of interactive explorer in understanding a provider’s API, publishing API will be easier. The options are therefore largely dictated by the choice of API specification format, for example:

  • The OpenAPI Specification (aka Swagger) offers Swagger UI, which allows you to generate an interactive explorer with virtually no coding (depending on the completeness of your Swagger specification);
  • Apiary offers an explorer that is generated from API Blueprint and Swagger specifications. It mixes the features of an interactive explorer with a documentation suite as it renders the Markdown documentation in API Blueprint side-by-side with an interactive tool for making sample API calls;
  • Finally, an open-source explorer is offered for the RAML specification format that implements many of the same features as Swagger UI and Apiary.

By using these tools, we hope you can create an easy-to –use reference point for their developer community. However, static documentation may be required to accompany an interactive explorer, if the subject matter of the API is complex or requires high-level explanation not necessarily associated with a resource.

Automatic Responsive Images with Client Hints

automatic-responsive-images-with-client-hints

There are many times where web developers have to wrestle with forcing images into responsive layouts. Due to this media queries and fluid grids are constantly employed to achieve visually flexible images. Achieving such flexible images as pointed out by Ethan Marcotte in the seminal first edition of his book is as easy as:

To make this code work effectively, you need to make sure that the image resources being served must be big enough to fill large viewports and high-resolution displays. Not only simply setting width on images, you may need to resize the images as well, or else huge image resources will be sent to everyone which is a performance disaster.

Or you can use the suite of new HTML features as another way to combat images into responsive layouts. This allows images to transform in a way that allows users get tailored resources based on their context. These features provide adaptation via allowing authors to mark-up multiple, alternate resources like so:

ywf2

This method can be tedious and complex for some people, since it always generates multiple alternate resources for every image. Cloudinary can help with the resource generation, but then the markup in our image tag will be overwhelming.

Considering JavaScript

The other method that developers usually use is by using JavaScript. JavaScript can directly measure the browsing context and when paired with on-the-fly, server-side resizing, it requests a single, perfectly-sized resource every time with little or no extra markup required. This post explains how to use JavaScript to achieve automatic responsive images.

Now there are challenges with this approach:

  1. Setting up JavaScript infrastructure which might be complex
  2. Inserting JavaScript between users and our page’s core content which might be tricky to do effectively.
  3. Browser vendors use the speculative pre-parser to shed off as many image loads as possible before a page’s HTML has even finished parsing. And for JavaScript to load measured image resources, it must wait for page layout to be complete before it can measure the page.

Due to this, we have two choices whether we wish to use JavaScript to load responsive images. Either :

  1. Let the pre-parser do its work and set JavaScript to double-load all of our images, or,
  2. Disrupt the pre-parser by authoring invalid src-less <img>s so that our JavaScript can start loading our pages’ images last, instead of first.

Client Hints To The Rescue

With the client hints, you don’t have to sweat yourself with all the options we considered above. In fact, you don’t need to use JavaScript anymore. The good news is that there is a fix! No, not throwing JavaScript at the challenge, but by asking the web server for a helping hand. Enter Client Hints, an initiative spearheaded by Google that is already available in browsers (Chrome and Opera) and that is super-simple to use. Let’s see how Client Hints can reduce both image size and verbosity of the responsive images markup.

Automatic DPR

In usual browsers you’ll see an image, the URL of which delivers different resources to different users, depending on their context. While in browsers that support Client Hints, 1x devices will receive 1x resources, 2x screens will receive 2x resources. This way is possible since a little tag is placed in the <head> of this page which looks like this:

<meta http-equiv=”Accept-CH” content=”DPR”>

You can use the code above to send an extra HTTP header named DPR, thus advertising devicePixelRatio. Those DPR HTTP headers are Client Hints. So, when you send DPR hints with a little meta magic and dpr_auto appended to the URL, Cloudinary is able to deliver different resources to different users depending on their display density.

Automatic Width

To fit different display densities, you can use code : dpr_auto scales images. Cloudinary provides w_auto which scales images to fit variable layout widths. You can take a look at the example below:

<meta http-equiv=”Accept-CH” content=”DPR, Width”>

 […snip…]

<img sizes=”100vw”

    src=”http://res.cloudinary.com/demo/w_auto/on_the_phone_csmn8h.jpg”

    alt=”Obama on the phone with Castro.” />

Here are some explanations about it:

  • The meta tag instructs the browser to send another Client hint: Width in addition to DPR.
  • The img tag includes a sizes attribute which informs the browser about the layout width of the image.
  • The browser then broadcasts the width to the server via the Width hint.

Advanced W-Auto Usage

Let’s take a look deeper about Cloudinary’s w_auto parameter. W_auto can use two optional parameters like this:

http://res.cloudinary.com/demo/w_auto:100:400/bike.jpg

:100 shows Cloudinary how big the difference between alternate resources should be. By defining a rounding step between them, this parameter allows you to limit the number of possible responses. For instance, if the target width is 323 pixels, Cloudinary will round up to the nearest hundred and return a 400 pixel-wide resource. However, if you place the parameter to :1, resources will be scaled to match the layout width exactly which is generally not a good idea.

:400 refers to the fallback width. This parameter will be used to serve an image resource with that width, if a browser doesn’t need send a width hint. For instance, browsers that don’t support Client hints, and this fallback parameter too is absent, w_auto will deliver images at their original size, since it will be impossible to load higher pixels, such as 12 megapixels to a site.

Create the Perfect Website Layout System

create-the-perfect-website-layout-system

If you are web developers or web designers who are looking for ways that can create sites that work on any device, this article is for you. In this opportunity, we are going to discuss about how to create the perfect website layout system. Take a look!

Multi-Column

You may not see multi-column as the most-used CSS columns in many websites. This is quite surprising, since it’s one of the most highly flexible techniques. In fact, this would be terribly suitable to be used by those who want perfection for lists of links, like navigations, footers, search results or photo blog.

However, multi-column may not be beautiful to be used for long passage article. This is because CSS columns will require people to scroll down and up again while reading.  The only wat to present your article nicely in CSS columns is by convincing your users to scroll horizontally.

To create a simple horizontally scrolling multi-column layout by setting the height of the article to a maximum of 100 percent of the viewport, and by telling it to use columns of no less than 20em. These few line is what it takes to create good multi-column:

article {
columns: 20em; /* never be smaller than 20em */
height: 100vh; /* be as high as the viewport */
width: 75vw; /* be 75% of the width of the viewport */
}

Flexbox and the Viewport

It may seem a bit like float, but much more powerful. With Flexbox, you can tell items what to do with any leftover white space. You can leave it at one of the ends, you can distribute it evenly between (or around) them, or you can choose to stretch the items – which basically gets rid of the white space. You can use this code to simply fit as many items on each row as possible.

ul {
display: flex;
flex-wrap: wrap;
font-size: 2.5em;
}

Viewport-relative units

You can use the vw unit, instead of using em and media queries to make sure our layout works in different viewports. However, in terms of text, viewport has a serious usability problem with using the viewport width as a unit for text though. At one point it can become too small to read on very small screens. The problem gets bigger when the user can’t increase the font size.

To avoid the font size becomes too small, you can use a calc function: font-size: calc(1em +1vw).

Viewport Calculations

To fit any text into any viewport with CSS, there’s a brilliant CodePen, such as explained in this line below:

font-size: calc(4vw + 4vh + 2vmin);

With this specific calculation, this one sentence, set in a certain font, will always fit in any viewport.

Quantity Selectors

By applying this technique, you can order the browser to behave in a certain manner. Instead of designing every possible layout for every possible screen size, you let the browser and the content figure it out together.

Container Queries

We can’t use element queries, but we might be able to use container queries. However, you cannot style the element itself; you could only style its children which cause something like this:

article:media( min-width: 30em ) screen {

}

Quantity Selectors

Quantity selectors are quite handy for search results, where you don’t know if there will be one single result or hundreds of them. Moreover, you can also change the way they look through the number of results. The selectors that make this possible look quite complex at first. At first, I didn’t understand how they worked at all. You can apply a fantastic job in explaining quantity selectors in this article:

article {
flex-basis: 100vmax;
}
article:nth-last-of-type(n + 2),
article:nth-last-of-type(n + 2) ~ article {
flex-basis: 50vmax;
}
article:nth-last-of-type(n + 6),
article:nth-last-of-type(n + 6) ~ article {
flex-basis: 33.33vmax;
}