How to make an API interface?

Ricky Kang — Wed, 27 Nov 2024 08:33:55 +0000

API is the application programming interface, it can be understood as a channel to communicate with different software systems. It is essentially a pre-defined functions.

API has many forms, the most popular one is to use HTTP protocol to provide services (such as: RESTful), as long as it meets the regulations can be used normally. Nowadays, many enterprises use APIs provided by third parties, and also provide APIs for third parties, so the design of APIs also needs to be careful.

How to design a good API interface?

Clarify Functionality
At the beginning of the design, you need to organize the functions of the API according to the business function points or modules to clarify that your API needs to provide.
Clear Code Logic
Keep your code tidy and add the necessary comments to ensure the interface has a single function. If an interface requires complex business logic, it is recommended to split it into multiple interfaces or encapsulate the functions into public methods independently to avoid too much code in the interface, which is not conducive to the maintenance and later iteration.
Necessary Security Checksum
A common solution is to use a digital signature. Add a signature to each HTTP request, and the server side verifies the validity of the signature to ensure the authenticity of the request.
Logging
Logging is essential to facilitate timely localization of problems.
Minimize Coupling
A good API should be as simple as possible. If the business coupling between APIs is too high, it is easy to cause an exception in a certain code, resulting in the unavailability of the relevant API. So it is better to avoid the complexity of the relationship between APIs as much as possible.
Return Meaningful Status Codes
Status code data should be carried in the API return data. For example, 200 means the request is normal, 500 means there is an internal error in the server. Returning a common status code is good for problem localization.
Development Documentation
Since API is provided for third-party or internal use, development documentation is essential, otherwise it would not be known to others how to use it.

A good API development documentation should contain the following elements:

API architecture model description, development tools and version, system dependencies and other environment information.
the functions provided by API.
API module dependencies.
invocation rules, notes.
deployment notes, etc.

How to develop an API interface?

If satisfied with the development environment, probably less than 10 minutes, you can complete the development of a simple API interface (just a demo).

Before development, you need to install the JDK, Maven and IDE.

Create a new project based on Spring Boot. In order to quickly complete, I choose to use (start.spring.io) to generate my project. Through [Search dependencies to add] you can choose the package. I only imported Spring MVC, if you need to access the database through Mybatis, you can also choose here, then click to generate the project.
Unzip the downloaded project and introduce it into your IDE, then to create a new class: com.wukong.apidemo.controller.ApiController.
Add a method in this class, the main use of @RestController, @RequestMapping, @ResponseBody tags.
The simplest API interface has been completed. We can start the project, access the corresponding interface address, and get the interface return information.
We can use swagger to help us generate the interface documentation and optimize the API interface.

More efficient way to make an API interface?

Both Python Flask and Java Spring Boot can be used to efficiently create an API interface.

Spring Boot has simplified the development process to a simple one. For python, I recommend a third-party package for developing API interfaces: fastapi.

It’s a fast and efficient tool with the following features:

Fast: comparable to NodeJS and Go. One of the fastest Python frameworks.
Fast coding: increases the speed of development by about 200% to 300%.
Fewer errors: reduces about 40% of errors caused by developers.
Simple: easy to use and learn. Less time spent reading documentation.
Standards-based: based on and fully compatible with API’s open standards.

Make a RESTful API with Python3 and Flask（Interface Testing Services and Mockserver Tool）

Build RESTful APIs seems to be the work of developer, in fact, there are many scenarios in which test developer needs to build RESTful APIs.

Some testers will build RESTful API, hijack the server-side domain name to their own API, and return all kinds of exceptions on purpose to see the stability of the client.

REST： REpresentational State Transfer
GET - /api/Category - Retrieve all categories
POST - /api/Category - Add a new category
PUT - /api/Category - Update a category
DELETE - /api/Category - Delete a category
GET - /api/Comment - Retrieve all the stored comments
POST - /api/Comment - Add new comment

Requirements：python3.*，PostgreSQL.

project/
├── app.py
├── config.py
├── migrate.py
├── Model.py
├── requirements.txt
├── resources
│   └── Hello.py
│   └── Comment.py
│   └── Category.py
└── run.py

Requirements.txt as follows:
Flask - microframework for python
Flask_restful - an extension to flask for quickly building REST API.
Flask_script - provides support for writing external scripts in flask.
Flask_migrate - use Alembic's Flask app for SQLAlchemy database migration.
Marshmallow - for complex data types and python data type conversions.
Flask_sqlalchemy - flask extension that adds support for SQLAlchemy.
Flask_marshmallow - the middle layer between flask and marshmallow.
Marshmallow-sqlalchemy - the middle layer between sqlalchemy and marshmallow.
psycopg - PostgreSQL API for python.

Install dependencies

# pip3 install -r requirements.txt

Install and Configure PostgreSQL(Take Ubuntu 16.04 as an example)

# sudo apt-get update && sudo apt-get upgrade
# apt-get install postgresql postgresql-contrib
# su - postgres
$ createdb api
$ createuser andrew --pwprompt #Create User
$ psql -d api -c "ALTER USER andrew WITH PASSWORD 'api';"

Configurations

from flask import Blueprint
from flask_restful import Api
from resources.Hello import Hello
from resources.Category import CategoryResource
from resources.Comment import CommentResource


api_bp = Blueprint('api', __name__)
api = Api(api_bp)

# Routes
api.add_resource(Hello, '/Hello')
api.add_resource(CategoryResource, '/Category')
api.add_resource(CommentResource, '/Comment')

Quick Start

app.py

from flask import Blueprint
from flask_restful import Api
from resources.Hello import Hello

api_bp = Blueprint('api', __name__)
api = Api(api_bp)

# Route
api.add_resource(Hello, '/Hello')

resource/Hello.py

#!/usr/bin/python
# -*- coding: utf-8 -*-
# Author:    xurongzhong#126.com wechat:pythontesting qq:37391319
# CreateDate: 2018-1-10

from flask_restful import Resource


class Hello(Resource):
    def get(self):
        return {"message": "Hello, World!"}

    def post(self):
        return {"message": "Hello, World!"}

run.py

from flask import Flask


def create_app(config_filename):
    app = Flask(__name__)
    app.config.from_object(config_filename)

    from app import api_bp
    app.register_blueprint(api_bp, url_prefix='/api')

    return app


if __name__ == "__main__":
    app = create_app("config")
    app.run(debug=True)

Starting services

$ python3 run.py
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 136-695-873

Use browser to visit: http://127.0.0.1:5000/api/Hello

{
    "hello": "world"
}

Access to databases

from flask import Flask
from marshmallow import Schema, fields, pre_load, validate
from flask_marshmallow import Marshmallow
from flask_sqlalchemy import SQLAlchemy


ma = Marshmallow()
db = SQLAlchemy()


class Comment(db.Model):
    __tablename__ = 'comments'
    id = db.Column(db.Integer, primary_key=True)
    comment = db.Column(db.String(250), nullable=False)
    creation_date = db.Column(db.TIMESTAMP, server_default=db.func.current_timestamp(), nullable=False)
    category_id = db.Column(db.Integer, db.ForeignKey('categories.id', ondelete='CASCADE'), nullable=False)
    category = db.relationship('Category', backref=db.backref('comments', lazy='dynamic' ))

    def __init__(self, comment, category_id):
        self.comment = comment
        self.category_id = category_id


class Category(db.Model):
    __tablename__ = 'categories'
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(150), unique=True, nullable=False)

    def __init__(self, name):
        self.name = name


class CategorySchema(ma.Schema):
    id = fields.Integer()
    name = fields.String(required=True)


class CommentSchema(ma.Schema):
    id = fields.Integer(dump_only=True)
    category_id = fields.Integer(required=True)
    comment = fields.String(required=True, validate=validate.Length(1))
    creation_date = fields.DateTime()

migrate.py

from flask_script import Manager
from flask_migrate import Migrate, MigrateCommand
from Model import db
from run import create_app

app = create_app('config')

migrate = Migrate(app, db)
manager = Manager(app)
manager.add_command('db', MigrateCommand)


if __name__ == '__main__':
    manager.run()

data migration

$ python3 migrate.py db init
$ python3 migrate.py db migrate
$ python migrate.py db upgrade

Testing
You can use curl, for example:

curl http://127.0.0.1:5000/api/Category --data '{"name":"test5","id":5}' -H "Content-Type: application/json"

DEV Community: Ricky Kang

How to make an API interface?

How to design a good API interface?

How to develop an API interface?

More efficient way to make an API interface?

Make a RESTful API with Python3 and Flask（Interface Testing Services and Mockserver Tool）