Mapear datos de un API a objetos nativos es uno de los pasos críticos al construir una app iOS que consume servicios externos. Aquí verás cómo transformar respuestas JSON de TheMovieDB en estructuras Swift usando Codable, paso a paso, para que cualquier desarrollador iOS principiante o intermedio pueda replicar el flujo en su propio proyecto.

El objetivo es claro: obtener un listado de programas de televisión populares y el detalle de cada uno, dejando lista la capa de datos antes de tocar la red o los repositorios.

Qué API usamos y qué endpoints consultamos

La fuente de datos es TheMovieDB, un API público que entrega información sobre películas, series y programas de televisión a nivel mundial. Para esta app necesitamos dos endpoints específicos.

• El endpoint de programas populares, que devuelve un JSON con un array de resultados.
• El endpoint de detalle de un programa, al que se accede mediante el identificador y devuelve valoraciones, resumen, géneros y más.

¿Qué es TheMovieDB? Es un API que provee datos de películas y series, incluyendo populares, detalles, valoraciones y géneros, ideal para apps de catálogo audiovisual.

La primera petición trae demasiados campos por elemento. No necesitas todos: solo los que vas a mostrar en pantalla. Esa decisión se traduce directamente en cómo defines tus modelos.

Por qué usar Codable para decodificar JSON en Swift

Cuando recibes una respuesta JSON, no puedes usarla tal cual en tu código Swift. Necesitas convertirla a un objeto que el lenguaje entienda, y ese proceso se llama decodificación.

Aquí entra Codable, un protocolo de Swift que automatiza la conversión entre JSON y objetos nativos. Si tu struct adopta Codable, el sistema se encarga de mapear cada campo del JSON a las propiedades de tu estructura, siempre que los nombres coincidan.

¿Qué hace Codable en Swift? Permite que una struct o class se convierta automáticamente desde JSON a objeto Swift y viceversa, sin escribir código manual de parsing.

Para que Codable funcione necesitas importar Foundation, que es donde vive esta librería [01:50].

Cómo crear el modelo TVShow para programas populares

Dentro del directorio Models creas un archivo nuevo llamado TVShow.swift. Ahí defines la estructura que representa un programa individual del listado.

swift import Foundation

struct TVShow: Codable { let id: Int let name: String let firstAirDate: String let voteAverage: Double }

Cada propiedad corresponde a un campo del JSON:

• id: identificador entero del programa.
• name: nombre del programa, tipo string.
• firstAirDate: fecha de lanzamiento en formato string.
• voteAverage: promedio de votación, tipo double.

Cómo envolver el array de resultados con PopularShowResponse

El endpoint de populares no devuelve directamente un array, devuelve un objeto JSON con una propiedad results que contiene el array. Por eso necesitas una segunda estructura que envuelva la respuesta completa [04:30].

swift struct PopularShowResponse: Codable { let results: [TVShow] }

Esta estructura es la que recibes en la primera petición. Dentro de results viene la lista de objetos TVShow que ya definiste arriba.

Cómo modelar el detalle con TVShowDetails y géneros anidados

El segundo archivo se llama TVShowDetails.swift y representa la información ampliada de un programa específico. Aquí el reto interesante: los géneros vienen como un array de objetos, no como simples strings.

swift import Foundation

struct Genre: Codable { let name: String }

struct TVShowDetails: Codable { let name: String let overview: String let genres: [Genre] }

Fíjate en el detalle: como genres en el JSON es un array con id y name por elemento, creas una struct aparte llamada Genre. En este caso solo te interesa el nombre, así que omites el identificador [06:45].

• name: título del programa.
• overview: resumen o sinopsis.
• genres: array de objetos Genre con los géneros asociados.

¿Cuándo necesito una struct anidada en Codable? Cuando un campo del JSON es un objeto o un array de objetos con su propia estructura interna, como pasa con los géneros en TheMovieDB.

Si más adelante quieres exponer otros campos como el lenguaje original o los videos relacionados, solo agregas la propiedad correspondiente a la struct y Codable hace el resto.

Por qué estos archivos viven en la capa de datos

Los modelos se ubican en el directorio Models porque pertenecen a la capa de datos de la arquitectura. Esa capa contiene representaciones de información que llega desde fuentes externas, en este caso un API REST.

Mantener los modelos separados de la lógica de red y de las vistas te permite reutilizarlos, testearlos de forma aislada y cambiar el origen de datos sin tocar el resto de la app. Con TVShow, PopularShowResponse, TVShowDetails y Genre ya tienes el contrato claro entre el JSON remoto y tu código Swift.

El siguiente paso natural es construir la lógica de red y los repositorios que ejecuten los endpoints y entreguen estas estructuras al resto de la aplicación. ¿Cómo organizas tú la capa de datos en tus proyectos iOS? Cuéntalo en los comentarios.