Как спроектировать реализацию API для веб-сайтов, используя колбу restplus?

Question

Я пишу REST API в колбе в первый раз,

так что теперь у меня есть что-то вроде этого:

import uuid
import pytz
from datetime import datetime
from flask_restplus import Resource, Api, fields
from ..models import publicip_schema

from ..controller import (
    jsonified,
    get_user_ip,
    add_new_userIp,
    get_specificIp,
    get_all_publicIp
    )

from flask import request, jsonify

from src import app
from src import db
from src import models

api = Api(app, endpoint="/api", versio="0.0.1", title="Capture API", description="Capture API to get, modify or delete system services")

add_userIp = api.model("Ip", {"ip": fields.String("An IP address.")})
get_userIp = api.model("userIp", {
    "ipid": fields.String("ID of an ip address."), 
    "urlmap" : fields.String("URL mapped to ip address.")
    })

class CaptureApi(Resource):

    # decorator = ["jwt_required()"]

    # @jwt_required()
    @api.expect(get_userIp)
    def get(self, ipid=None, urlmap=None):
        """
           this function handles request to provide all or specific ip
        :return:
        """
        # handle request to get detail of site with specific location id.
        if ipid:
            ipobj = get_user_ip({"id": ipid})
            return jsonified(ipobj)

        # handle request to get detail of site based on  site abbreviation
        if urlmap:
            locate = get_user_ip({"urlmap": urlmap})
            return jsonified(locate)

        return jsonify(get_all_publicIp())

    # @jwt_required()
    @api.expect(add_userIp)
    def post(self, username=None):
        """
            Add a new location.
            URI /location/add
        :return: json response of newly added location
        """
        data = request.get_json(force=True)
        if not data:
            return jsonify({"status": "no data passed"}), 200

        if not data["ip"]:
            return jsonify({"status" : "please pass the new ip you want to update"})

        if get_user_ip({"ipaddress": data["ip"]}):
                return jsonify({"status": "IP: {} is already registered.".format(data["ip"])})

        _capIpObj = get_user_ip({"user_name": username})

        if _capIpObj:
            # update existing ip address
            if "ip" in data:
                if _capIpObj.ipaddress == data["ip"]:
                    return jsonify({"status": "nothing to update."}), 200
                else:
                    _capIpObj.ipaddress = data["ip"]
            else:
                return jsonify({
                    "status" : "please pass the new ip you want to update"
                    })

            db.session.commit()
            return jsonified(_capIpObj)
        else:
            device = ""
            service = ""
            ipaddress = data["ip"]
            if "port" in data:
                port = data["port"]
            else:
                port = 80
            if "device" in data:
                device = data["device"]
            if "service" in data:
                service = data["service"]
            date_modified = datetime.now(tz=pytz.timezone('UTC'))
            urlmap = str(uuid.uuid4().get_hex().upper()[0:8])    
            new_public_ip = add_new_userIp(username, ipaddress, port, urlmap, device, service, date_modified)
            return publicip_schema.jsonify(new_public_ip)


api.add_resource(
    CaptureApi,
    "/getallips",  # GET
    "/getip/id/<ipid>",  # GET
    "/getip/urlmap/<urlmap>",  # GET
    "/updateip/username/<username>" # POST
                 )

Я столкнулся с двумя проблемами

1. если я укажу

   get_userIp = api.model("userIp", { "ipid": fields.String("ID of an ip address."), "urlmap" : fields.String("URL mapped to ip address.") })

и добавить @api.expect(get_userIp) по методу get выше. Я вынужден передавать необязательные параметры с любым значением (даже чтобы получить список всех ip, т.е. из "/getallips"): см. Скриншот ниже.

но эти параметры не обязательны, чтобы пометить все IP, но мне нужно использовать эти параметры, чтобы получить IP на основе ipid, или же urlmap с использованием get метод.

2. глядя на чванство документации, сгенерированной flask_restplus.Api я вижу

get и post для всех конечных точек, тогда как я определил конечную точку только get и post. Так технически updateip/username/<username> не должно быть в списке get

Как это исправить?

Answer 1

Хороший вопрос! Вы можете исправить обе проблемы, определив отдельные Resource подклассы для каждой из ваших конечных точек. Вот пример, где я разделяю конечные точки для "/ getallips", "/ getip / id /" и "/ getip / urlmap /".

Ip = api.model("Ip", {"ip": fields.String("An IP address.")})
Urlmap = api.model("UrlMap", {"urlmap": fields.String("URL mapped to ip address.")})

@api.route("/getallips")
class IpList(Resource):
    def get(self):
        return jsonify(get_all_publicIp())

@api.route("/getip/id/<ipid>")
class IpById(Resource):
    @api.expect(Ip)
    def get(self, ipid):
        ipobj = get_user_ip({"id": ipid})
        return jsonified(ipobj)

@api.route("/getip/urlmap/<urlmap>")
class IpByUrlmap(Resource):
    @api.expect(Urlmap)
    def get(self, urlmap):
        ipobj = get_user_ip({"id": ipid})
        return jsonified(ipobj)

Обратите внимание, что вы решаете свои expect проблема бесплатно - поскольку каждая конечная точка теперь полностью определяет свой интерфейс, к ней легко прикрепить четкое ожидание. Вы также решаете "получить и опубликовать определенные для конечных точек, которые не должны", вы можете решить для каждой конечной точки, должна ли она иметь get или же post,

Я использую api.route декоратор вместо вызова api.add_resource для каждого класса из-за личных предпочтений. Вы можете получить такое же поведение, позвонив api.add_resource(<resource subclass>, <endpoint>) за каждый новый Resource подкласс (например, api.add_resource(IpList, "/getallips"))