Introducción a API Star

API Star es un marco de API de alto rendimiento que le permite construir API web con facilidad. Está diseñado para ser simple, intuitivo y escalable, lo que lo convierte en una opción ideal para construir aplicaciones tanto pequeñas como a gran escala.

Historia

API Star fue creado por Tom Christie, el mismo desarrollador detrás del popular marco Django REST. Fue lanzado por primera vez en 2017 y desde entonces ha ganado mucha popularidad dentro de la comunidad de Python.

Características

1. Anotaciones de tipo

API Star aprovecha el poder de las anotaciones de tipo de Python para proporcionar validación automática de solicitudes y respuestas. Esto le permite definir los tipos esperados para sus datos de entrada y salida, lo que ayuda a detectar posibles errores desde el principio.

Aquí hay un ejemplo de cómo usar las anotaciones de tipo con API Star:

from apistar import http, App, Route

def hello(name: str) -> dict:
    return {'message': f'Hola, {name}!'}

routes = [
    Route('/hello/{name}/', method='GET', handler=hello),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.serve('127.0.0.1', 8000)

En este ejemplo, la función hello toma un parámetro name de tipo str y devuelve un diccionario. API Star validará automáticamente el tipo del parámetro name y el valor de retorno, asegurando que se cumpla el contrato de la API.

2. Documentación automática

API Star genera automáticamente una documentación integral para su API. Esta documentación incluye detalles sobre los puntos finales disponibles, los formatos de solicitud y respuesta esperados, y cualquier parámetro adicional o encabezado requerido.

Para ver la documentación generada, simplemente navegue a /docs en su navegador web después de ejecutar su API.

3. Autenticación y permisos

API Star proporciona soporte integrado para autenticación y permisos. Puede integrar fácilmente esquemas de autenticación populares como OAuth, JWT o claves de API en su API.

Aquí hay un ejemplo de cómo usar la autenticación con API Star:

from apistar import http, App, Route, annotate

def require_authentication() -> annotate(permissions=[IsAuthenticated]):
    pass

def hello(user: User) -> dict:
    return {'message': f'Hola, {user.username}!'}

routes = [
    Route('/hello/', method='GET', handler=hello, permissions=[require_authentication]),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.serve('127.0.0.1', 8000)

En este ejemplo, la función require_authentication se utiliza como decorador de permiso para el punto final hello. Esto asegura que solo los usuarios autenticados puedan acceder al punto final. El parámetro user se completa automáticamente con el objeto de usuario autenticado.

4. Integración de bases de datos

API Star se integra perfectamente con bases de datos populares como PostgreSQL, MySQL y SQLite. Puede definir fácilmente modelos y realizar operaciones de base de datos utilizando el ORM incorporado.

Aquí hay un ejemplo de cómo usar el ORM con API Star:

from apistar import http, App, Route, annotate
from apistar.backends import SQLAlchemy

app = App()
app.add_database(SQLAlchemy('sqlite:///mydatabase.db'))

class User(app.orm.Model):
    __tablename__ = 'users'

    id = app.orm.Column(app.orm.Integer, primary_key=True)
    username = app.orm.Column(app.orm.String)

def list_users() -> list[User]:
    return User.query.all()

routes = [
    Route('/users/', method='GET', handler=list_users),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.serve('127.0.0.1', 8000)

En este ejemplo, se define el modelo User utilizando el ORM SQLAlchemy. La función list_users recupera todos los usuarios de la base de datos y los devuelve como una lista de objetos User.

5. Soporte para middleware

API Star admite el uso de middleware, lo que le permite modificar las solicitudes y respuestas en varias etapas del ciclo de solicitud/respuesta. Esto es útil para tareas como autenticación, registro, manejo de errores y más.

Aquí hay un ejemplo de cómo usar el middleware con API Star:

from apistar import http, App, Route

def authentication_middleware(request: http.Request, handler) -> http.Response:
    # Realice la lógica de autenticación aquí
    authenticated = True

    if not authenticated:
        return http.Response('No autorizado', status=401)

    response = handler(request)
    return response

def hello() -> dict:
    return {'message': '¡Hola, Mundo!'}

routes = [
    Route('/', method='GET', handler=hello),
]

middleware = [authentication_middleware]

app = App(routes=routes, middleware=middleware)

if __name__ == '__main__':
    app.serve('127.0.0.1', 8000)

En este ejemplo, la función authentication_middleware intercepta la solicitud y realiza la lógica de autenticación. Si el usuario no está autenticado, se devuelve una respuesta 401 No autorizado. De lo contrario, se llama a la función del controlador y se devuelve la respuesta tal cual.

Ejemplos

Ejemplo 1: Hola Mundo

from apistar import http, App, Route

def hello() -> dict:
    return {'message': '¡Hola, Mundo!'}

routes = [
    Route('/', method='GET', handler=hello),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.serve('127.0.0.1', 8000)

Salida:

{"message": "¡Hola, Mundo!"}

Ejemplo 2: Parámetros de URL

from apistar import http, App, Route

def hello(name: str) -> dict:
    return {'message': f'Hola, {name}!'}

routes = [
    Route('/hello/{name}/', method='GET', handler=hello),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.serve('127.0.0.1', 8000)

Salida:

GET /hello/John/
{"message": "¡Hola, John!"}

Ejemplo 3: Parámetros de consulta

from apistar import http, App, Route

def hello(name: str, age: int) -> dict:
    return {'message': f'Hola, {name}! Tienes {age} años.'}

routes = [
    Route('/hello/', method='GET', handler=hello),
]

app = App(routes=routes)

if __name__ == '__main__':
    app.serve('127.0.0.1', 8000)

Salida:

GET /hello/?name=John&age=25
{"message": "¡Hola, John! Tienes 25 años."}

Para obtener más información, puede visitar la documentación oficial de API Star.