Why documentation drives adoption in Rest API - See It in Action

Why Documentation Drives Adoption

📖 Scenario: Imagine you are creating a simple REST API for a book store. You want other developers to use your API easily. Good documentation helps them understand how to use your API quickly and correctly.

🎯 Goal: Build a small REST API with clear documentation comments that explain each endpoint. This will show how documentation helps others adopt your API.

📋 What You'll Learn

Create a basic REST API with at least two endpoints

Add clear documentation comments for each endpoint

Use descriptive names and simple explanations

Show how documentation helps users understand the API

💡 Why This Matters

🌍 Real World

Good API documentation helps developers quickly understand how to use your services, reducing confusion and support requests.

💼 Career

Many software jobs require writing clear API documentation to help teams and external users adopt your code efficiently.

1

Set up the basic REST API structure

Create a simple REST API using Flask. Define an app variable with Flask(__name__) and create two endpoints: /books and /authors that return simple JSON lists.

Rest API

from flask import Flask, jsonify

app = Flask(__name__)

# Your code here

Need a hint?

Remember to import Flask and jsonify, then create the app and define two routes with functions returning JSON lists.

2

Add configuration for documentation style

Add a variable called doc_style and set it to 'simple' to represent the style of documentation you will add.

Rest API

from flask import Flask, jsonify

app = Flask(__name__)

doc_style = 'simple'  # Your code here

Need a hint?

Just create a variable named doc_style and assign it the string 'simple'.

3

Add documentation comments to each endpoint

Add a docstring to the get_books function that says: """Return a list of book titles.""" and to the get_authors function that says: """Return a list of author names.""".

Rest API

from flask import Flask, jsonify

app = Flask(__name__)

doc_style = 'simple'

@app.route('/books')
def get_books():
    # Add docstring here
    return jsonify(['Book A', 'Book B', 'Book C'])

@app.route('/authors')
def get_authors():
    # Add docstring here
    return jsonify(['Author X', 'Author Y', 'Author Z'])

Need a hint?

Use triple quotes right after the function definition to add the docstring.

4

Run the app and print confirmation

Add the code to run the Flask app with app.run() inside a if __name__ == '__main__': block. Then print "API is running with simple documentation style".

Rest API

from flask import Flask, jsonify

app = Flask(__name__)

doc_style = 'simple'

@app.route('/books')
def get_books():
    """Return a list of book titles."""
    return jsonify(['Book A', 'Book B', 'Book C'])

@app.route('/authors')
def get_authors():
    """Return a list of author names."""
    return jsonify(['Author X', 'Author Y', 'Author Z'])

# Your code here

Need a hint?

Use the if __name__ == '__main__' block to run the app and print the message before starting.