Most people embrace blogging as a way of communicating their opinions, feelings, and other stories. As the Internet has grown and evolved, blogs have become increasingly significant as a tool that individuals, businesses, and other entities use to exert their online presence.
Interestingly, some of the blogging platforms have exposed their APIs (Application Programming Interfaces) to enable developers to integrate their functionalities into their applications.
We looked at several blogger APIs based on the following four main factors:
- API features: We assessed the various features of each of the blogger APIs.
- Popularity: We reviewed the popularity of the blogging platforms. This will assist you to know their extent of usage and whether integrating them could enhance your reach.
- Price: We examined the cost of using each of the APIs.
- Ease of use: We reviewed the ease of embedding the APIs for powering communication in applications.
Eventually, we created the following list of top 10 best blogger APIs.
- WordPress API
- Wikipedia API
- Reddit API
- Tumblr API
- Medium API
- Blogger API
- Wix API
- Quora API
- Weebly API
- Serverless blogging API
What Developers Hate in API Documentation
The dev community is a passionate one. It’s specifically passionate about the things they don’t like. If they don’t like an API, it’s most of the time because of junky docs, even if the product is actually great. Here are some common issues devs have with API docs.
It’s not written using simple human language. This is a common problem for auto-generated docs or docs that are neglected by creators. Although many documentation generation tools are doing a great job at commenting on the code, they cannot replace actual explanations in English written by a developer or technical writer.
It has very few code samples. This is another end of the spectrum where explanations are abundant, but there are minimal examples of the actual code.
It’s available only to registered users. This not-so-slick maneuver does nothing for your marketing. It only frustrates the people who want to know what your API does before deciding if they want it (as any sane person would).
It’s too long/can’t be found/inaccurate/hasn’t been updated in years, etc. Creating good docs is almost as important as building a good API. Because poorly written docs or the ones that can’t be found by simply googling “Product API” are failing the whole development effort. If you’re interested, we’ve already outlined specifics of technical documentation in general. But API docs deserve a dedicated article. So how do you write great API docs?
Adopt spec-driven development
Spec-driven development (SDD) is similar to test-driven development in which you write test cases for each feature and then write code that should pass them. In SDD, you create docs or at least some parts of it in parallel with building an API, often following a certain API description format called a specification.
An API specification is like a template of your future docs, the unified language that describes the design of your API, explains how it functions and what to expect from it. There are a few specifications, such as RAML (RESTful API Modeling Language), OpenAPI (formerly Swagger), and API Blueprint, but there’s a trend going on for combining all specs under the hood of OpenAPI.
These specs have prebuilt documentation tools that allow for writing and managing your docs. For example, API Console automatically generates docs from RAML and OpenAPI formats and helps you run it on your existing web application or as a standalone app.
About REST APIs
In a nutshell, REST APIs (which are a type of web API) involve requests and responses, not too unlike visiting a web page. You make a request to a resource stored on a server, and the server responds with the requested information. The protocol used to transport the data is HTTP. “REST” stands for Representational State Transfer.
I dive more into the principles of REST in What is a REST API? In your REST API documentation, you describe the various endpoints available, their methods, parameters, and other details, and you also document sample responses from the endpoints.
From practice to documentation
In this course, after you practice using an API like a developer, you’ll then shift perspectives and “become a technical writer” tasked with documenting a new endpoint that engineers added to an API. As a technical writer, you’ll tackle each element of a reference topic in REST API documentation:
1.Resource descriptions
2.Endpoints and methods
3.Parameters
4.Request example
5.Response example
Exploring each of these sections will give you a solid understanding of how to document REST APIs. You’ll also learn how to document the conceptual sections for an API, such as the getting started tutorial, product overview, status and error codes, request authorization, and more.
You’ll also dive into different ways to publish REST API documentation, exploring tools and specifications such as GitHub, static site generators like Jekyll, and other docs-as-code approaches. You’ll learn how to leverage templates, build interactive API consoles so users can try out requests and see responses, and learn how to manage your content through version control.
We’ll also dive into specifications such as the OpenAPI specification and Swagger UI (which provides tooling for the OpenAPI specification). Additionally, you’ll learn how to document native library APIs and generate Javadoc.
Tech writing is about more than tools and technology, though. As such, I even explore processes and methodologies in depth, explaining how to manage both large and small documentation projects, how to collect documentation feedback, how to keep stakeholders happy and updated, and more.
I’ve also included a section on metrics and measurement, which lists a comprehensive quality checklist. The criteria described can help you evaluate your own developer portal in myriad ways against industry best practices.
Throughout this course, I put these concepts in real, applicable contexts with hands-on activities and demos.
Technical writers can use their own way for documenting their APIs.
Who the course is for
The course primarily serves the following audiences:
Professional technical writers looking to transition from traditional documentation into more API-focused documentation for developers.
Students learning how to prepare themselves technically to succeed in the tech comm field, which is becoming more focused on developer documentation.
Developers who are documenting their own APIs and want to know best practices for structure, terminology, and style with tech docs.
Educators who are training technical writing students about API documentation practices and technologies.
Course organization
The course consists of the following sections:
I: Introduction to REST APIs
II: Using an API like a developer
III: Documenting API endpoints
IV: OpenAPI spec and generated reference docs
V: Step-by-step OpenAPI code tutorial
VI: Testing API docs
VII: Conceptual topics in API docs
VIII: Code tutorials
IX: The writing process
X: Publishing API docs
XI: Thriving in the API doc space
XII: Native library APIs
XIII: Processes and methodology
XIV: Metrics and measurement
XV: Additional resources
Sequence and activities
You don’t have to read the sections in order — feel free to skip around as you prefer. Some of the earlier sections (such as the section on Using a REST API like a developer and Documenting endpoints follow a somewhat sequential order with the same weather API scenario, but by and large you can jump around as desired.
Because the purpose of the course is to help you learn, there are many activities that require hands-on coding and other exercises. Along with the learning activities, there are also conceptual deep dives, but the focus is always on learning by doing. Where there are hands-on activities, I typically include this icon in the section title: . Other topics have the word “Activity” in the title. The activities are integrated into various sections, but you can also see many of the activities in the Workshop Activities. These are the activities we do during live workshops.
