Welcome to apicore’s documentation!

Set of core libraries usefull for building REST API and Microservices based on Flask.

The code is open source, release under MIT and written in Python 3.

apt-get install build-essential python3-dev
pip install apicore

Features

  • Cross-origin resource sharing (CORS) ready
  • Data caching with redis server or direct in memory
  • Configuration file loader
  • A simple Logger
  • Raise exception conform to HTTP status codes
  • Authorization using JSON Web Token(JWT) issued from an OpenID Connect provider
  • OpenAPI 3.0 specification embedded with Swagger UI

Example

#!/usr/bin/env python

from apicore import api, Logger, config, Http409Exception, Authorization

Logger.info("Starting {} API Server...".format(config.app_name))


@api.route('/error/')
def error():
    """
    summary: Raise an execption
    responses:
      409:
          description: Conflict
    """
    raise Http409Exception()


@api.route('/jwt/')
def jwt():
    userProfile = Authorization()
    print(userProfile);
    return "JWT Valid!"


if __name__ == "__main__":
    api.debug = config.debug
    api.run()

Configuration

Configuration is set in conf/config.yaml file (see apicore.config.Config).

Name Default value Description
app_name “Meezio” Application’s name.
debug True Active debug mode.
issWhitelist None Whitelist for OIDC issuers. If not set, every issuers are allowed except ones from blacklist.
issBlacklist None Blacklist for OIDC issuers. synaxte : same as ‘iss’ claim in the JWT.
prefix “” Add a prefix to URL path (ie: “/api”).
redis None Redis server used for caching data : redis://:password@localhost:6379/0. If not set use memory.
smtp_host “localhost” SMTP server used to sent email.
swagger_ui “/” Relative URL path to embedded Swagger UI (prefix + swagger_ui).
tokenExpire True Check ‘exp’ claim in JWT to validate token.

OpenAPI 3.0

  • See specification for syntax.
  • Document route’s methods with Operation Object using yaml syntax.
  • Document your API in conf/openapi.yaml file.
  • Access your documentation through a python dictionary : api.oas.specs.
  • Your spec is available at http[s]://<hostname>/openapi.json.
  • Default path to http[s]://<hostname>/ to see your spec with Swagger UI (set swagger_ui in conf/config.yaml to change path)
  • Full exemple :
@api.route('/sellers/<idseller>/', methods=['GET', 'PUT'])
def seller(idseller):
    """
    description: "Path Item Object" level here, only common_responses is added to OpenAPi specification. Next level are "Operation Object".
    parameters:
      - name: idseller
        in: path
        description: uuid of seller
        required: true
        type: string
        format: uuid
    common_responses:
        400:
         description: Invalid request
        401:
          description: Authentification required
        403:
          description: Ressource access denied
        500:
          description: Server internal error
    ---
      tags:
        - profile
      summary: Find a seller profile by ID
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Seller'
        404:
          description: Ressource does not exist
        406:
          description: Nothing to send maching Access-* headers
    ---
      tags:
        - profile
      summary: Update seller profile
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Seller'
          required: true
      responses:
        200:
          description: Success
    """
    pass


    print(api.oas.spec)

APIs

Todo

  • i18n HTTP response messages.
  • Configure using command line argument and environnement variables which override configuration file.