RFC 
 TOC 
yes   J.C. Gregorio 
  BitWorking, Inc 
  December 2003 

AtomAPI
draft-gregorio-09.html

Nota de Traducción

Este documento se encontrará en estado de borrador durante un periodo indefinido de tiempo dedicado a efectuar las correcciones oportunas. Esta traducción se concluyó el 31 de enero de 2004. (Los posibles errores presentes en este documento, debidos a la traducción, son de la responsabilidad del traductor y no son achacables en modo alguno al autor original). Para cualquier comentario sobre la traducción dirigirse a Pedro Palazón Candel

Este documento se encuentra localizado originalmente en las páginas del autor.

La única versión normativa oficial de este documento es la versión original (en inglés): http://bitworking.org/projects/atom/draft-gregorio-09.html

Resumen

Esta memoria presenta una técnica para usar XML (Extensible Markup Language) y HTTP (HyperText Transport Protocol) para editar contenido.

Para proporcionar retroalimentación sobre el borrador de este RFC visite por favor Atom Wiki o participe en la  lista de correo de la sintáxis de atom.


 RFC 
 TOC 

Tabla de Contenidos

Introducción
Terminología
Ámbito
Introducción
 4.1  Propósito
 4.2  Terminología
 4.3  El modelo de AtomAPI
Especificación Funcional
 5.1  PostURI
  5.1.1  Localizando
  5.1.2  Petición
  5.1.3  Respuesta
   5.1.3.1  201
   5.1.3.2  303
   5.1.3.3  400
   5.1.3.4  500
 5.2  EditURI
  5.2.1  Localizando
  5.2.2  Petición
 5.3  FeedURI
  5.3.1  Localizando
  5.3.2  Petición
  5.3.3  Respuesta
   5.3.3.1  301
   5.3.3.2  307
 5.4  Etiqueta Link
  5.4.1  rel
  5.4.2  href
  5.4.3  title
  5.4.4  type
 5.5  Restricciones del cuerpo de las Peticiones y Respuestas de Atom
  5.5.1  id
  5.5.2  link
  5.5.3  title
  5.5.4  summary
  5.5.5  content
  5.5.6  issued
  5.5.7  modified
  5.5.8  created
  5.5.9  author
  5.5.10  contributor
  5.5.11  generator
Consideraciones de Seguridad
Apéndices
 7.1  Habilitando SOAP
  7.1.1  Servidoress
  7.1.2  Clientes
 7.2  Ejemplo para un weblog
 7.3  Ejemplo para un wiki
Histórico de Revisiones
Copyright
§  Referencias
§  Señas del Autor
§  Acuerdo de Copyright Completo


 TOC 

1  Introducción

AtomAPI es un protocolo a nivel de aplicación para publicar y editar recursos web. El protocolo en su núcleo es el transporte mediante HTTP de representaciones con formato Atom.

Para proporcionar retroalimentación sobre el borrador de este RFC visite por favor Atom Wiki o participe en la  lista de correo de la sintáxis de atom.


 TOC 

2  Terminología

Los términos "DEBE", "NO DEBE", "REQUERIDO", "DEBERÍA", "NO DEBERÍA", "RECOMENDADO", "PUEDE", y "OPCIONAL" de este documento han de ser interpretados tal y como se describe en RFC2119.

Para una breve descripción del significado de estos términos en castellano, puede consultar la sección de Terminología de la traducción al castellano de la especificación XHTML 1.0


 TOC 

3  Ámbito

Este documento cubre la edición de contenido de un sitio web de actualización periódica usando HTTP y XML. Todos los pagos XML están en formato Atom, que se encuentra documentado en el borrador Formato de suscripción Atom RFC.


 TOC 

4  Introducción

4.1  Propósito

AtomAPI es un protocolo a nivel de aplicación para publicar y editar recursos web.

4.2  Terminología

Entrada Atom
Un fragmento de un alimentador Atom completo. En este caso el fragmento es un único elemento 'entry' y todos sus elementos hijos.
PostURI
Un URI que se emplea para crear nuevos recursos. POSTeando un Atom Entry a este URI crearemos un nuevo recurso.
EditURI
Un URI que se emplea para editar un recurso. La edición se realiza empleando los verbos HTTP GET, PUT y DELETE. La representación del recurso siempre es un Atom Entry.
FeedURI
Un URI que representa un Atom feed completo.

4.3  El modelo de AtomAPI

AtomAPI es un protocolo a nivel de aplicación para publicar y editar recursos web. Usando los verbos HTTP comunes proporciona un patrón para trabajar con todos como recursos web:

Hay diferentes tipos de recursos manejados por AtomAPI, cada uno de los cuales tiene URIs y dichos URIs coportan un subconjunto de los siguientes métodos. Existen tres clases principales de URIs en esta especificación: PostURI, FeedURI y EditURI. Este especificación define las acciones esperadas para cada uno de los métodos listados. Notar que esto no restringe a un URI a soportar únicamente los métodos listados, por ejemplo un EditURI podría soportar un método POST, o el método OPTIONS, lo que hagan dichos métodos está más allá del ámbito de esta especificación.

Este RFC no especifica la forma de los URIs que serán empleados. El espacio del URI de cada servidor está controlado, como se ha definido por HTTP, por cada servidor. Lo qu eespecifica este RFC son los formatos de los archivos que son intercambiados y las acciones que pueden realizar sobre los URIs embebidos en dichos archivos.


 TOC 

5  Especificación Funcional

5.1  PostURI

PostURI se emplea para crear entradas. Estas pueden ser tanto entradas completas, como los post de un weblog, o pueden ser comentarios, o incluso una página de un wiki. El cliente POSTea un Atom Entry relleno a este URI. Si la respuesta es correcta se crearán nuevos  URIs múltiples que contendrán representaciones de varios tipos. Por ejemplo, POSTeando una entrada Atom a un PostURI podemos crear una nueva entrada de un weblog con representaciones HTML y Atom disponibles desde este momento. El URI de la recién creada representación de Atom puede ser de hecho un EditURI a través del cual el nuevo recurso puede ser editado.

5.1.1  Localizando

Para crear una nueva entrada en el sitio web, se emplea la etiqueta link. Notar que la etiqueta link se emplea tanto en HTML como en el formato de Atom. Una etiqueta link con el siguiente formato apunta al PostURI para un sitio web. En HTML las etiquetas link se encuentran siempre en el elemento head, mientras que en Atom pueden aparecer como hijos de los elementos Feed y entry.

                                <link rel="service.post"
type="application/x.atom+xml"
href="URI para Publicar aquí"
title="El nombre del sitio.">

Nota: Multiples etiquetas link pueden aparecer juntas y pueden distinguirse porque tienen diferentes atributos 'rel', 'type' y 'title'.

5.1.2  Petición (Request)

La petición contendrá un elemento Atom entry, sujeto a las restricciones de la sección @@ TBD @@.

5.1.3  Respuesta (Response)

Los códigos de estado esperados, que para POST son 201, 303, 400, y 500. 401, 404, y 410 también son posibles.

5.1.3.1  201

La respuesta incluye una cabecera Location: con el URI del recurso creado, e.d. el URI usado para editar la entrada, como opuesto al URI empleado para mostrar el contenido. El cuerpo de la respuesta contendrá la entrada "rellenada" con las estampaciones de tiempo y cualquier otro dato que el servidor elija revelar. Debe contener suficiente información para habilitar al cliente para poder proceder a un subsecuente PUT a esta localización. Notar que el sevidor puede elegir omitir el contenido en la respuesta, particularmente si esta es larga.

5.1.3.2  303

El cuerpo de esta respuesta no contiene la entrada rellenada, pero la entrada rellenada puede encontrarse bajo un URI diferente y DEBERÍA ser devuelto empleando el método GET sobre dicho recurso. Los diferentes URI DEBERÍAN ser dados por el campo Location en la respuesta.

5.1.3.3  400

Indica que el servidor cree que los datos enviados constituyen una petición inválida. Una breve descripción del error aparecerá en la propia línea de estado. Una descripción mayor lo hará en el cuerpo de la respuesta.

5.1.3.4  500

Indica que el servidor ha detectado un error interno en el procesado de la petición (como una excepción imprevista). Una breve descripción del error aparecerá en la propia línea de estado. Una descripción mayor lo hará en el cuerpo de la respuesta..

5.2  EditURI

EditURI se emplea para editar una sola entrada. Cada entrada que sea editable DEBE tener un URI único. Este URI soportará tanto GET como PUT que serán empleados en tandem en un ciclo de edición. El cliente obtiene vía GET la representación formateada como una entrada Atom. Dicho cliente podrá entonces actualizar la entrada y devolverla al mismo URI empleando PUT. El envío vía PUT causará que todos los recursos relacionados sean actualizados, por ejemplo, la representación HTML.

Notar que el valor del elemento content en la entrada de Atom no tiene que corresponderse exactamente con el elemento content para la misma entrada cuando se representa en un alimentador Atom. Por ejemplo, un servidor puede permitir al cliente enviar entradas vía post cuyo contenido esté formateado como WikiML, y a continuación el servidor puede limpiar dicho marcado y transformarlo en XHTML bien formado antes de colocarlo en el alimentador público de Atom. Otro escenario son los sumarios, EditURI es para la edición del contenido completode una entrada, pero el servidor puede presentar sólo extractos cuando produce un alimentador Atom.

Un cliente enviará un DELETE a EditURI para borrar una entrada.

5.2.1  Localizando

Para editar un elemento Entry de un sitio web, se emplea la etiqueta link. Notar que la etiqueta link se emplea tanto en HTML como en el formato de Atom. Una etiqueta link con el siguiente formato apunta al EditURI de un sitio web. En HTML las etiquetas link se encuentran siempre en el elemento head, mientras que en Atom pueden aparecer como hijos de los elementos Feed y entry.

                                <link rel="service.edit"
type="application/x.atom+xml"
href="URI para edición viene aquí"
title="Descripción legible del elemento entry.">

Nota: La característica crítica de esta etiqueta link es el @rel de 'service.edit' y el @type de 'application/x.atom+xml'.

5.2.2  Petición (Request)

Una petición PUT, y una respuesta GET conteniendo ambas un elemento Atom entry rellenado, sujetas a las restricciones en la sección @@ TBD @@.

5.3  FeedURI

FeedURI se emplea para recuperar una representación en formato Atom. Notar que este alimentador (feed) es diferente de un alimentador Atom típico porque contiene elementos "link" para la navegación y la manipulación del contenido del sitio web. Por ejemplo debería haber un elemento "link" con rel="next" cuyo URI apuntase al siguiente bloque de entradas en el sitio web. Similarmente el elemento feed puede contener un elemento "link" con rel="service.post", cuyo URI es un PostURI. Las entradas individuales deberían contener elementos "link" con rel="service.edit" cuyos URIs fuesen EditURIs.

@@ Nota del Editor: @@ Notar que "service.feed" toma el lugar del archivo de Introspección y de la faceta de busqueda en versiones previas de la especificación. Es decir, el descubrimiento de facetas, que se realizaba previamente inspeccionando el archivo de introspección se realiza ahora buscando etiquetas "link" con un atributo "rel" cuyo valor se haya fijado a "service.[something]" en el archivo "service.feed". Al mismo tiempo la misma representación reemplaza la faceta de búsqueda mediante la presencia de etiquetas "link" que apuntan a otros alimentadores feeds empleando atributos 'rel' bien conocidos con valores tales como 'next' y 'prev', o la búsqueda puede ramificarse en multiples direcciones especificando múltiples etiquetas con rel="service.feed" y teniendo atributos title diferentess que anuncien el tipo de resultados de búsqueda en dicho alimentador.

5.3.1  Localizando

Una etiqueta link con el siguienteformato apunta a un FeedURI.

                                <link rel="service.feed"
type="application/x.atom+xml"
href="URI aquí"
title="El nombre del sitio web.">

5.3.2  Petición (Request)

La petición es un simple GET. Ningún otro verbo ha sido especificado a actualmente para este URI.

5.3.3  Respuesta (Response)

Los códigos de estado esperados para un GET son 200, 301, 307, y 500. 401, 404, y 410 también son posibles.

5.3.3.1  301

El Feed ha sido movido permanentemente, el nuevo URI se da en la cabecera Location.

5.3.3.2  307

El Feed ha sido movido temporalmente, el nuevo URI se da en la cabecera Location.

5.4  Etiqueta Link

La etiqueta link es empleada tanto en HTML como en el formato de Atom. Hay diferencias significativas ente los dos usos. Aquí se exponen las coincidencias, las diferencias, y una lista de los valores bien conocidos para el atributo rel.

La etiqueta link en documentos HTML aparece en el 'head' del documento. La sección 'head' permite sólo una lista lineal de etiquetas 'link'. El formato Atom permite etiquetas 'link' como hijos tando del elemento 'feed' omo del elemento 'entry'. Notar que esto nos da la información presente en la etiqueta link en mayor contexto. Por ejemplo ... @@ TBD @@

5.4.1  rel

Este atributo describe la relación del documento actual, sea este de tipo HTML o Atom, al ancla especificada por el atributo href. El valor de este atributo es una lista separada por espacios de tipos de link. Notar que estos valores no son sensibles al empleo de mayúsculas o minúsculas. Con type="application/x.atom+xml" tendremos las siguientes interpretaciones de la relación.

alternate
El URI en el atributo href apunta a un arepresentación alternativa del recurso que contiene.
start
El alimentador Atom en el URI especificado en el atributo href contiene el primer alimentador en una secuencia lineal de entradas.
next
El alimentador Atom en el URI especificado en el atributo href contiene las siguientes N entradas en una secuencia lineal de entradas.
prev
El alimentador Atom en el URI especificado en el atributo href contiene las N entradas previas en una secuencia lineal de entradas.
service.edit
El URI en el atributo href es empleado para editar una representación del recurso referenciado.
service.post
El URI en el atributo href es empleado para crear nuevos recursos.
service.feed
El URI en el atributo href es un punto de partida para la navegación del contenido y los servicios.

5.4.2  href

URI del recurso que está siendo descrito por este elemento link.

5.4.3  title

Ofrece información de consulta sobre el link. Renderizado hacia el usuario para ayudarle a elegir entre una serie de links con idénicos atributos rel y type.

5.4.4  type

El tipo de contenido del recurso disponible en el URI del atributo href del elemento link. La mayoría de los tipos de link en esta especificación son del tipo 'application/x.atom+xml'.

5.5  Restricciones del cuerpo de las Peticiones y Respuestas Atom

El formato Atom se emplea como representación de todos los recursos resources en esta especificación. Como es utilizado en diferentes contextos, existen diferentes para los distintos elementos en los que PUEDE estar presente, y cómo deberían ser interpretados su valores.

5.5.1  id

PostURI
NO DEBE estar presente.
FeedURI
DEBE estar presente.
EditURI
GET
DEBE estar presente.
PUT
DEBE estar presente.

5.5.2  link

PostURI
PUEDE estar presente. Los servidores pueden emplear la información para determinar el URI del recurso creado. Los URLs relativos han de ser interpretados relativamente a xml:base.
FeedURI
DEBE estar presente.
EditURI
GET
DEBE estar presente.
PUT
DEBE estar presente.

5.5.3  title

PostURI
DEBE estar presente. El elemento puede estar vacío, para indicar explícitamente "ningún título". Los servidores NO DEBERÍAN tratar de generar un título si no se proporciona ninguno. El atributo type PUEDE estar presente, y si no lo está se considerará por defecto "text/plain". Si está presente, DEBE representar un tipo mime que soprte el servidor. El atributo mode PUEDE estar presente, si no se considerará por defecto "xml". Si está presente, debe ser "xml", "base64", o "escaped".
FeedURI
DEBE estar presente.
EditURI
GET
DEBE estar presente.
PUT
DEBE estar presente. El elemento puede estar vacío, para indicar explícitamente "ningún título". Los servidores NO DEBERÍAN tratar de generar ningún título si no se proprciona ninguno.

5.5.4  summary

PostURI
PUEDE estar presente, si no está presente, indica que se da la bienvenida al servidor para que produzca su propio summary. Si está presente pero vacío, entonces el servidor NO DEBERÍA generar su propio summary. El atributo type PUEDE estar presente, y si no lo está se considerará por defecto "text/plain". Si está presente, DEBE representar un tipo mime que soprte el servidor. El atributo mode PUEDE estar presente, si no se considerará por defecto "xml". Si está presente, debe ser "xml", "base64", o "escaped".
FeedURI
PUEDE estar presente.
EditURI
GET
PUEDE estar presente.
PUT
PUEDE estar presente. El elemento puede estar vacío, para indicar explícitamente "ningún sumario". Los servidores NO DEBERÍAN tratar de generar un sumario si este no se proprciona.

5.5.5  content

PostURI
PUEDE estar presente pero puede estar vacío para indicar explícitamente "ningún contenido". El atributo type PUEDE estar presente, y si no lo está se considerará por defecto "text/plain". Si está presente, DEBE representar un tipo mime que soprte el servidor. El atributo mode PUEDE estar presente, si no se considerará por defecto "xml". Si está presente, debe ser "xml", "base64", o "escaped".
FeedURI
PUEDE estar presente.
EditURI
GET
PUEDE estar presente.
PUT
PUEDE estar presente. El elemento puede estar vacío, para indicar explícitamente "ningún contenido".

5.5.6  issued

PostURI
DEBE estar presente pero puede estar vacío, en cuyo caso significa "ahora" en la zona temporal del servidor.
FeedURI
DEBE estar presente.
EditURI
GET
DEBE estar presente.
PUT
DEBE estar presente. La política del servidor determinará si se acepta un tiempo de actualización.

5.5.7  modified

PostURI
NO DEBE estar presente.
FeedURI
PUEDE estar presente.
EditURI
GET
PUEDE estar presente.
PUT
PUEDE estar presente. El elemento puede estar vacío, para indicar explícitamente que 'ahora' en el tiempo del servidor va a ser empleado.

5.5.8  created

PostURI
PUEDE estar presente.
FeedURI
PUEDE estar presente.
EditURI
GET
PUEDE estar presente.
PUT
PUEDE estar presente. El servidor puede o no aceptar un valor de actualización. Si el servidor no permite actualización del tiempo especificado en issued cualquier petición PUT con un valor diferente de issued DEBE ser rechazada.

5.5.9  author

PostURI
PUEDE estar presente. Si noestá presente el servidor determinará el autor. Si está presente y entra en conflicto con valores válidos determinados por el sevidor, entonces el servidor cambiará los valores para el autor.
FeedURI
PUEDE estar presente.
EditURI
GET
PUEDE estar presente.
PUT
PUEDE estar presente.

5.5.10  contributor

PostURI
PUEDE estar presente.
FeedURI
PUEDE estar presente.
EditURI
GET
PUEDE estar presente.
PUT
PUEDE estar presente.

5.5.11  generator

PostURI
DEBE estar presente. El valor del elemento indica el código base empleado para crear l apetición. DEBE contener un URI válido. DEBE tener también un atributo 'version' con un número de versión.
FeedURI
NO DEBE estar presente.
EditURI
GET
NO DEBE estar presente.
PUT
NO DEBE estar presente.

 TOC 

6  Consideraciones de Seguridad

@@TBD@@ Hablar aquí sobre el empleo de auntenticación y obtención de información HTTP.

@@TBD@@ Hablar aquí acerca de la denegación de ataques de servicios usando archivos XML largos, o el ataque del billón de carcajadas de la DTD.


 TOC 

7  Apéndices

7.1  Habilitando SOAP

Todos los servidores DEBERÍAN soportar los siguientes mecanismos de interfaz alternativa para habilitar una variedad amplia de clientes para interactuar con servidores AtomAPI. Los siguientes requisitos se añaden a los listados en la sección Especificación Funcional. Si un server soporta la habilitación SOAP entonces DEBE soportar lo siguiente.

7.1.1  Servidores

  1. Todos los servidores DEBEN soportar el uso limitado de la cabecera HTTP SOAPAction tal y como se describe más abajo en la sección de Clientes.
  2. Todos los servidores DEBEN ser capaces de procesar XML bien formado. Los servidores no necesitan ser capaces de manejar instrucciones de procesado o DTDs.
  3. Los servidores DEBEN aceptar contenido en un SOAP Envelope (Envoltorio SOAP), y si reciben una petición envuelta en unSOAP Envelope entonces DEBEN encerrar sus respuestas en envoltorios SOAP o producir un SOAP Fault.

7.1.2  Clientes

  1. Los clientes DEBERÍAN emplear el método HTTP apropiado cuando sea posible. Cuando no sea posible, deberían usar POST e incluir una cabecera HTTP SOAPAction restringida del modo siguiente: SOAPAction: "http://schemas.xmlsoap.org/wsdl/http/[METHOD]" Donde [METHOD] es reemplazado por el método HTTP deseado.
  2. Los Clientes PUEDEN encerrar sus monedas de cambio XML en un SOAP Envelope. Si lo hacen, deberían encerrarlas en un elemento que coincida exactamente con el método HTTP.

7.2  Ejemplo para un weblog

Rellenar esto con un ejemplo que explíque como se emplea lo anterior para un weblog. Comenzar con la página principal HTML, etiqueta link con type service.feed al archivo de 'introspección'. 1. Crear una nuev aentrada 2. Buscar una entada vieja 3. editar uan entrada vieja 4. comentarios en una entrada (vía HTML y Atom)

7.3  Ejemplo para un wiki

Rellenar esto como arriba, para un wiki.


 TOC 

8  Histórico de Revisiones

Rev 09 - 10Dec2003 - Añadida la sección sobre servidores y clientes SOAP.

Rev 08 - 01Dec2003 - Refactorizada la especificación, incluido el archivo de Introspección en el formato del feed. Además se elimina la sistinción entre el tipo de URI empleado para crear nuevas entradas y el empleado para crear comentarios. Eliminadas las preferencias de usuario.

Rev 07 - 06Aug2003 - Eliminado el uso de un archivo RSD para auto-descubrimiento. Cambiado el copyright haste que sea elegido un cuerpo final estándar. Modificados los parámetros del para la faceta de búsqueda de modo que todos comiencen con atom- para prevenir colisiones de nombres. Actualizados todos los Entries para seguir la versión 0.2. Cambiado el formato de los resultados de búsqueda y el archivo de plantillas a una sintáxis basada puramente en elementos.

Rev 06 - 24Jul2003 - MOvimiento a PUT para la actualización de entradas. Cambiados los tipos mime a application/x.atom+xml. Añadida la edición de plantillas. Cambiado 'edit-entry' a 'create-entry' en el archivo de introspección para reflejar con más cuidado su propósito.

Rev 05 - 17Jul2003 - Renombrado todo de Echo a Atom. Añadidos números de versión en el histórico de revisiones. Cambiados todos los tipos mime a application/atom+xml.

Rev 04 - 15Jul2003 - Actualizada la versión de RSD empleada de 0.7 a 1.0. Cambiado el modo de borrar una entrada de POSTeando <delete/> al uso del verbo HTTP DELETE. También cambiada la interfaz de peticiones a GET en lugar de POST. Movido el Descubrimiento de la Introspección para ser colocado bajoIntrospección. Introducido el término 'faceta' para los servicios listados en el archivo de Introspección.

Rev 03 - 10Jul2003 - Añadido un link al Wiki cerca del principio del documento. Añadida la sección para buscar una entrada. Devolución de un aentrada ahora en su propia sección. Cambiado el código de estado HTTP para la edición satisfactoria de una entrada a 205.

Rev 02 - 7Jul2003 - Las entradas ya no serán devueltas vía POSTs, en lugar de ello, lo serán vía GET. Limpiadas las imágenes de los títulos, ya que son renderizadas con pobreza en HTML. Todos los content-types han sido cambiados a application/atom+xml.

Rev 01 - 5Jul2003 - Renombrado desde EchoAPI.html para seguir el formato de nombres más usado: draft-gregorio-NN.html. Renombradas todas las referencias de URL a URI. Separada introspección en su propia sección. Añadida la sección Histórico de Revisiones. Añadido más contenido a la advertencia de que los URIs de ejemplo no son normativos.


 TOC 

9  Copyright

Copyright (C) Joe Gregorio (2003). Todos los derechos reservados.


 TOC 

Referencias

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.

 TOC 

Señas del Autor

  Joe Gregorio
  BitWorking, Inc
  1002 Heathwood Dairy Rd.
  Apex, NC 27502
  US
Phone:  +1 919 272 3764
EMail:  joe@bitworking.com
URI:  http://bitworking.com/
 

Nota del traductor: En el futuro se incorporarán, adicionalmente a las referencias a los originales en inglés, referencias a las versiones en castellano de cuantos documentos se encuentren traducidos.