[Actualización 16/01/2013] 

Me ha parecido que se ha quedado

muy corto la construcción del esquema de datos y lo he alargado
un poco más.

La llegada de Internet ha revolucionado en profundidad tanto el

mundo de las telecomunicaciones, como el de la información,
como el de la arquitectura de software.

La evolución de los sistemas SOA, basados en servicios “pesados”

en XML y encapsulados en complejos mensajes SOAP, han ido
perdiendo terreno ante las nuevas capas de servicios
construidas sobre los verbos HTTP (GET, POST, PUT y DELETE), y
que intercambian la comunicación por medio de los propios
mecanismos del protocolo – como los datos en el cuerpo o
encabezado – y el uso estándar de notación JSON para la
transferencia de información.

Presentación del tutorial

Este tutorial va a llevarte de la mano en la elaboración de una
API REST sencilla, que será capaz de realizar un CRUD sobre
un tipo de objeto complejo. Es decir, inserción, recuperación,
modificación y borrado de unidades de información.

Para ello he utilizado el framework de ASP.NET Web API, y Fiddler

Web Debugger como herramienta para realizar las pruebas
funcionales; como base de datos MS SQL Server Express; y como
lenguajes de programación C#, Linq y Entity Framework. (No voy a
utilizar async/await).

El resultado final serán cinco métodos REST diferentes:

* POSThttp:///api/persona/ (Inserta una nueva persona).
* GET http:///api/persona/1 (Recupera la persona con Id 1).
* GET http:///api/persona/ (Recupera todas las personas).
* PUT http:///api/persona/ (Actualiza los datos de una persona).
* DELETE http:///api/persona/ (Borra una persona).
Si te has fijado, con estos cinco métodos, cubro más del 80% de
las necesidades de cualquier API. Y las construcciones que quedan
son para llamadas complejas de datos, como paginación,
ordenamiento o campos de selección y recuperación.

Ecosistema de desarrollo

El segundo objetivo de este tutorial es el compartir con los

lectores de GenbetaDev el ecosistema de desarrollo que
utilizo en mi labor profesional diaria, haciendo énfasis en utilizar
versiones gratuitas (o de prueba gratuita).

Para ello, a continuación, añado los enlaces a las herramientas que

he utilizado en la elaboración de esta pequeña serie: * Visual
Studio 2013 Premium o Ultimate – Trial 90 dias. * SQL 2012
Express with Tools * Fiddler Web Debugger

Empezando con los datos

Una vez instalado el SQL, me acuerdo de configurarlo para que
se pueda acceder a él por medio de login y password, accedo a
la instancia con SQL Manager.

A continuación creo una nueva base de datos llamada

GenbetaDevWebApi.
A continuación creo una nueva tabla dentro de la base de datos
recién implementada.

Continuo con la construcción del esquema, añadiendo y

definiendo las columnas o campos que van a almacenar la
información de la persona.
El uso de un Id Autonumérico (Identity), es una buena
práctica en la mayoría de los escenarios de tablas de datos. El
resto de los campos, como ves, son los esperados en la unidad de
información del tipo Persona.

Para finalizar, introduzco un juego de datos que explotaré en su

momento, y que serán los que se accederán a través de la Api.

Y ya está, poniéndole el nombre “Personas” a la nueva tabla,

tengo el esquema de datos sobre el que voy a trabajar construido.

En el próximo capítulo entraré en la construcción de la estructura

MVC de la aplicación Web.Api, integrando Entity Framework, y
creando un Controller que me haga el Crud.

Y así, lo prometo, tendré mi Web Api plenamente funcional en

menos de una hora.
En el capítulo anterior hice la presentación de este mini tutorial de
iniciación, que tiene como objetivo el construir una API básica
REST con ASP.NET Web Api.

A estas alturas debes tener tu SQL, o SQL Express, instalado, con

la base de datos, la tabla personas y algo de contenido
almacenado. Así podré mostrarte cómo utilizar Entity
Framework 5 (lo ideal sería el 6, pero requiere instalarlo con
Nuget) como ORM, y a partir de él construir los métodos públicos
de la API.

Alta de proyecto Web API desde

Visual Studio
Abro el Visual Studio (en mi caso es un 2013) y accedo al menú
“File” para dar de alta un nuevo proyecto.

El tipo de proyecto que he elegido es de Visual C#, del

subconjunto Web, del tipo ASP.NET Web Application. Observando
la aplicación de la nueva filosofía de Microsoft, en donde todas
son aplicaciones ASP.NET, y más adelante se específica de qué
“sabor”.
Ahora escojo cual es la plantilla que quiero utilizar, la cual es la de
Web Api. Además selecciono que voy a utilizar la arquitectura de
MVC, con las librerías de Web API, por supuesto que me dé de
alta automáticamente el proyecto de test unitarios (no son
opcionales), y sin ningún tipo de código de autenticación.

Ok. Ya tengo mi flamante proyecto Web API junto al proyecto de

Testing.

Alta del esquema de datos con EF5

Ahora voy a utilizar las capacidades del ORM por defecto
de .NET, Entity Framework 5, para utilizar el esquema de datos
que tengo construido en mi base de datos.

Para ello, sobre el proyecto GenbetaDevWebApi, pulso el botón

derecho y navego por el menú contextual hasta “New Item…”.

Aquí escojo el tipo “ADO.NET Entity Data Model”, y renombro el

fichero para quitarle la cifra que pone por defecto al final; que me
parece espantoso.
Y empieza el asistente de creación del modelo y su contexto,
pidiéndome lo primero la forma en que voy a trabajar. Si con un
modelo vacío desde el que luego se construirá la base de datos, o
al revés. En este caso selecciono “Generar desde la base de datos”.

Así lo siguiente que me pide VS es la conexión que quiero utilizar,

la cual la creo nueva con el formulario estándar en Windows para
definirlas.
Ahora que ya he definido la conexión, y comprobado que se
conecta correctamente a la base de datos, sigo rellenando el
formulario indicando -ojo, es un agujero de seguridad- que
almacene las credenciales de conexión en el propio web.config de
la aplicación.

Y le indico también el nombre con que quiero que inserte el valor

de la cadena de conexión en el fichero de configuración.
El asistente me indica qué objetos puedo insertar en el futuro
esquema de entidades, y he seleccionado las tablas, ya que es lo
único que tengo.

Seleccionar “Pluralize or singularize generated object names”, es

muy cómodo para que las tablas se escriban en plural, pero las
entidades que contiene se escriban en singular. Es decir, la tabla
Personas contiene entidades del tipo Persona.
Después de pulsar en el botón “Finalizar”, el sistema se pondrá a
pensar, hacer “magia” y, finalmente, se abrirá el diagrama de mi
esquema de entidades sobre la que se mapea la base de datos. En
el “Explorador de la Solución” me aparece un montón de
referencias nuevas y un fichero Model.edmx.

En el siguiente capítulo de este tutorial de iniciación a ASP.NET

Web API, construiremos por fin el controlador que expondrá los
métodos de un CRUD completo sobre el contenido de la tabla
personas, a través de una API REST.
En el capítulo anterior configuré el ORM estándar de .NET, Entity
Framework 5, y realicé el mapeado de la tabla de datos que
construí en el primero.

Este capítulo trataré sobre la construcción en sí de la API Rest con

Web API, mostrando como en unos pocos click y selecciones la
tendré funcionando y lista para ser probada con Fiddle.

Un CRUD REST casi automáticamente

Teniendo abierto el proyecto de Web API en Visual Studio, pulso
con el botón derecho sobre la carpeta de “Controllers” para
obtener el menú contéxtual. Aquí selecciono “Add” o “Añadir”
(depende del idioma de tu instalación) y vuelvo a escoger “New
Scaffolded Item…”.

En la ventana que se abre selecciono la plantilla de Web API 2

Controller con acciones, utilizando Entity Framework.
Lo cual me lleva a otra pequeña ventana en donde le cambio el
nombre al Controller a PersonasController.

La importancia de escoger bien el nombre es que con esta

denominación se construirá el servicio REST y así, en este ejemplo,
las llamadas se realizarán a /api/Personas. Teniendo muy en
cuenta que es sensible a las mayúsculas, y el no utilizar símbolos
como las ñ o los acentos.

Como verás, tengo a continuación un aviso de que estoy

utilizando EF 5, por lo cual no voy a poder obtener una API que
funcione de forma asíncrona con este ayudante. Lo cual es una
pena, pero que veremos en otro capítulo más de este tutorial.

Lo siguiente que debo hacer es seleccionar cual es la entidad que

vamos a utilizar en el controlador para transmitir/recibir la
información.

Y lo último es elegir el contexto de datos que voy a utilizar. Es

decir el conjunto de entidades, operaciones y mapeado en Entity
Framework que me permitirán manipular la base de datos. Y que
en este tutorial (si has seguido los nombres que he ido poniendo)
debe ser la que se lee en la siguiente imagen.
Y ya está. Se ha generado automáticamente los siguientes
métodos, plenamente accesibles por medio de una API REST, que
conforman un CRUD de objetos del tipo Personas contra la base
de datos SQL. * GetPersonas. Devuelve un listado de todas las
personas almacenadas en la base de datos. * GetPersona(int id).
Devuelve una persona identificada por su Id. * PutPersona(int id,
Persona persona) Modifica una persona identificada por su Id.
* PostPersona(Persona persona) Inserta una nueva persona.
* DeletePersona(int id) Borra una persona identificada por su Id.

Probando la funcionalidad real de la

API
Todo este tutorial podría llegar a ser de cierta utilidad tal cual,
pero creo que puedo aportar un calor añadido describiendo cómo
he realizado las pruebas – manuales, eso sí – de la API, y confirmar
que hace lo que parece que hace. Así que lo primero es descargar
he instalar una herramienta excelente para este tipo de
operaciones: Fiddler.

Al abrirlo veo una pantalla vacía, en donde la sección de la

derecha voy a escoger la pestaña “Composer”. Aquí introduciré un
poco más adelante las peticiones que le voy a hacer a la API.

Me vuelvo al Visual Studio y arranco el “Debug”. Ya sea con la

tecla F5 o con el botón de Play. Sabré que tengo la sesión
arrancada, primero porque se me va a abrir un navegador que
muestra una web tipo de asp.net que se publica con el servidor
web de desarrollo (por eso el puerto de localhost).

Segundo, por la barra naranja que se ve en el pie del Visual

Studio, y que indica el modo en el que está funcionando el IDE.
Ahora vuelvo a Fiddler e introduzco la dirección del IIS de
desarrollo (la que se ve en la imagen es la mia, la tuya
posiblemente utilice otro puerto). Y le
añado /api/Personas. Cuidado con no poner la / al final.

Para no recibir toda la información de todos los procesos abiertos

y que se comuniquen con Internet, primero pongo la pantalla de
Fiddler lado a lado con el navegador en donde tengo corriendo la
API.

Entonces en Fiddle selecciono el icono de la mira, y arrastro el

picker encima de la ventana del navegador. Y con esto Fiddler
escuchará y mostrará solamente el tráfico en esta sesión del
navegador.

El siguiente paso es volver a poner Fiddler en pantalla completa, y

pulsar la tecla F12, para iniciar la escucha. Y pulso en el botón de
“Execute” al lado derecho de la url.
La respuesta no se hace esperar, y obtengo un resultado 200 que
significa que todo ha ido bien. Ahora, para ver la respuesta solo
debo hacer un doble click y Fiddler me ofrece el contenido de la
misma.

Tal y como esperaba, he obtenido una lista de todas las personas

almacenadas en la base de datos.

Y si introduzco ahora un número en la url...

... me devuelve la persona a la que pertenece es Id.

Ahora voy a hacer algo un poquito más complejo. Voy a

actualizar los datos de una persona.

Para ello lo primero que hago es seleccionar el ver la respuesta de

la petición anterior en formato “Raw”. Y me copio el objeto
persona en formato Json.
¿Por qué? Porque ASP.NET Web API tiene una curiosa forma de
recibir los parámetros. Si es un objeto primitivo como una cadena
de texto, un entero, un boleano, o similares, dichos objetos se
mandan por querystring. Pero los objetos complejos siempre se
mandan en el cuerpo del mensaje (en realidad se puede cambiar
todo esto, pero está fuera del alcance de este tutorial).

Ahora cambio el tipo de mensaje http de GET a PUT he

introduzco en el cuerpo del mensaje el objeto persona que he
copiado anteriormente. Tal y como se ve en la imagen a
continuación.

Ups, al lanzar la ejecución, el API me devuelve un error “415

Unsupported Media Type” que lo que viene a decir es que no sabe
cómo tratar la información que introducido en el cuerpo. Pero
esto se arregla fácil añadiendo en la cabecera del mensaje el tipo
de contenido: Content-type: application/json

Y ahora sí, el API ha realizado la modificación y me devuelve el

objeto modificado.

El resto de las pruebas, te las dejo a ti. Pero puedo asegurarte

que todos los métodos son plenamente funcionales.

Espero que este tutorial haya sido de utilidad y que la sencillez de

construcción de esta API REST motive a los lectores en
adentrarse en el apasionante mundo del backend.
En los tres últimos capítulos he recorrido las instalaciones y
configuraciones fundamentales para poder implementar una API
REST con tecnología .NET (más bien Microsoft).

Este capítulo voy a tratar la habilitación de CORS en mi API. Es

decir, el permitir que se hagan llamadas AJAX desde JavaScript,
desde direcciones (dominios) diferentes a la del servidor. Lo cual
es un agujero de seguridad en muchos casos, pero que es
imprescindible para una API pública (aunque debería, entonces, de
implementar seguridad de acceso).

Habilitando Cross-origin resource

sharing
La descripción detallada de porqué los navegadores impiden el
acceso vía AJAX a dominios diferentes del dominio del servidor, es
algo que escapa del alcance de este tutorial de iniciación, pero
que tengas claro que está prohibido por una buena razón, y
que habilitarlo solo lo deberías hacer si estás en desarrollo o si
tienes una buena política de autenticación de acceso a la API.

La forma más sencilla de habilitar CORS es utilizando las

capacidades de NuGet para localizar e instalar el código
necesario. Así pulso con el botón derecho del ratón encima del
icono de la solución y selecciono, en el menú contextual que
obtengo, la opción de "Gestionar paquetes NuGet de la solución...".
En la ventana que se abre, escojo "Online" en las opciones del
menú vertical de la izquierda y escribo en la casilla de búsqueda
en la esquina superior derecha la palabra "cors". Después de un
ratito - dependiendo de la velocidad de conexión a la Red - me
aparecen varios resultados de entre los cuales escojo "Microsoft
ASP.NET Web API 2.x Cross-Origin Support", y pulso en el botón de
"Instalar".
Lo siguiente que me pregunta el asistente es los proyectos en
donde quiero instalar CORS, y le he dicho que en todos los del
tutorial.

Antes de iniciar la instalación completa, debo aceptar las licencias

de uso de todo lo que se va a instalar y configurar. Y, como todo
el mundo, no me leo ni una de ellas y continúo.
Ahora sí, se lía a desinstalar, buscar y resolver dependencias e
instalar las versiones más recientes y aquellas que son necesarias.
Acabando, finalmente, el proceso; y marcando las características
añadidas a mis proyectos.

Ahora toca picar un poquito de código para habilitar y definir

cuáles son los dominios que pueden atacar mi API vía AJAX. Para
ello abro la carpeta App_Start y edito el fichero WebApiConfig.cs.
¿Qué le estoy diciendo con estas dos líneas de código añadido?
En la segunda línea estoy habilitando las comunicaciones Cross
Domain, y en la primera línea le indico que le dé acceso a
cualquier dominio de origen (el primer asterísco). Aquí podría
indicar cada uno de los dominios permitido, separandolos por una
coma ("www.midominio1.com, www.midominio2.es").

Pero esto requiere que añada un nuevo espacio de nombres por

medio de un using en la cabecera de la clase referenciando a:
"System.Web.Http.Cors".

Y con esto ya tengo lista mi API para ser consumida desde

cualquier punto de Internet.