API de fotos.red

Introducción

La API de fotos.red es una API RESTful que utiliza JSON para el intercambio de datos. Está diseñada para permitir:

• Acceso a perfiles de usuario, publicaciones y comunidades
• Creación y gestión de contenido
• Interacción con el contenido (me gusta, comentarios, etc.)
• Búsqueda y descubrimiento de contenido

Base URL

Formatos de Respuesta

Todas las respuestas son devueltas en formato JSON con los siguientes componentes estándar:

{
  "success": true,
  "data": { ... },  // Los datos solicitados
  "meta": {         // Metadatos sobre la respuesta (paginación, etc.)
    "pagination": {
      "total": 100,
      "count": 20,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 5,
      "links": {
        "next": "https://api.fotos.red/v1/endpoint?page=2"
      }
    }
  }
}

En caso de error, la respuesta seguirá este formato:

{
  "success": false,
  "error": {
    "code": 404,
    "message": "El recurso solicitado no existe",
    "details": { ... }  // Información adicional sobre el error (opcional)
  }
}

Autenticación

La API de fotos.red utiliza OAuth 2.0 para la autenticación de aplicaciones y usuarios.

Obtener Credenciales

Para usar la API, necesitas registrar tu aplicación en el Portal de Desarrolladores. Tras el registro, recibirás un client_id y un client_secret.

Flujo de Autenticación

Utilizamos dos tipos de autenticación:

1. Autenticación de Cliente (para endpoints públicos)

Para acceder a datos públicos sin actuar en nombre de un usuario:

curl -X POST https://api.fotos.red/v1/oauth/token \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

2. Autenticación de Usuario (para actuar en nombre de un usuario)

Utiliza el flujo de autorización para obtener permisos del usuario:

1. Redirige al usuario a la URL de autorización:

   https://fotos.red/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=read write

2. Recibe el código de autorización:

   El usuario será redirigido a tu redirect_uri con un parámetro code.

3. Intercambia el código por un token de acceso:

   curl -X POST https://api.fotos.red/v1/oauth/token \
     -d "grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Usar el Token de Acceso

Una vez obtenido el token, inclúyelo en todas las solicitudes en el encabezado de autorización:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.fotos.red/v1/users/me

Scopes

Los scopes definen el nivel de acceso que tu aplicación tiene. Los scopes disponibles son:

• read: Lectura de datos
• write: Creación y modificación de contenido
• delete: Eliminación de contenido
• profile: Acceso a datos del perfil del usuario
• messages: Acceso a mensajes privados

Endpoints

Aquí tienes un resumen de los principales endpoints disponibles en la API de fotos.red:

Usuarios

Obtener Perfil de Usuario

Recupera la información del perfil de un usuario por su nombre de usuario.

GET /users/{username}

Respuesta:

{
  "success": true,
  "data": {
    "id": 12345,
    "username": "fotografo_pro",
    "display_name": "Carlos Rodríguez",
    "bio": "Fotógrafo profesional especializado en naturaleza y paisajes.",
    "profile_picture": "https://fotos.red/uploads/profiles/user12345.jpg",
    "followers_count": 1250,
    "following_count": 345,
    "posts_count": 98,
    "is_verified": true,
    "is_followed_by_me": false,  // Solo si hay un usuario autenticado
    "created_at": "2023-01-15T14:30:00Z",
    "website": "https://carlosrodriguez.com"
  }
}

Listar Publicaciones de un Usuario

Obtén las publicaciones realizadas por un usuario específico.

GET /users/{username}/posts

Parámetros de consulta:

• page: Número de página (predeterminado: 1)
• per_page: Resultados por página (predeterminado: 20, máximo: 50)
• sort: Ordenamiento (recent, popular)

Seguir a un Usuario

Permite que el usuario autenticado siga a otro usuario.

POST /users/{username}/follow

Respuesta:

{
  "success": true,
  "data": {
    "following": true,
    "followers_count": 1251
  }
}

Dejar de Seguir a un Usuario

Permite que el usuario autenticado deje de seguir a otro usuario.

DELETE /users/{username}/follow

Respuesta:

{
  "success": true,
  "data": {
    "following": false,
    "followers_count": 1250
  }
}

Límites de la API

Para garantizar un servicio estable y justo para todos los desarrolladores, implementamos límites de tasa en nuestra API:

Los límites se aplican por token de acceso y por aplicación.

Encabezados de Límite de Tasa

Cada respuesta incluye encabezados que indican tu estado actual de límite de tasa:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1626969600

Políticas y Mejores Prácticas

Directrices de Uso

• No almacenes datos de usuarios por períodos prolongados
• Respeta la privacidad de los usuarios
• No suplantes identidades ni engañes a los usuarios
• No hagas scraping ni uso automatizado excesivo
• Mantén actualizada tu aplicación según los cambios en la API
• No utilices la API para distribuir contenido prohibido o ilegal

Mejores Prácticas

• Implementa caché para reducir solicitudes duplicadas
• Utiliza paginación para conjuntos de datos grandes
• Solicita solo los campos que necesitas usando el parámetro fields
• Maneja adecuadamente los errores y reintentos
• Mantén tus tokens de acceso seguros

Recursos para Desarrolladores