How to make an API interface?

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?

1. 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.




2. 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.




3. 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.




4. Logging
   
   Logging is essential to facilitate timely localization of problems.




5. 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.




6. 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.




7. 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:

1. API architecture model description, development tools and version, system dependencies and other environment information.


2. the functions provided by API.


3. API module dependencies.


4. invocation rules, notes.


5. 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.

1. 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.




2. Unzip the downloaded project and introduce it into your IDE, then to create a new class: com.wukong.apidemo.controller.ApiController.




3. Add a method in this class, the main use of @RestController, @RequestMapping, @ResponseBody tags.




4. The simplest API interface has been completed. We can start the project, access the corresponding interface address, and get the interface return information.




5. 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:

{

    "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"