Como mencioné en la introducción, la idea al finalizar esta serie de publicaciones es tener las herramientas y el conocimiento para poder convertirnos expertos en API Testing, por tanto poder manejar y tener claridad de los conceptos es esencial. No vamos a crear un diccionario, ya que haría la publicación muy larga si buscamos definir todo, así que el enfoque va a ser definir lo que vamos a estar utilizando en nuestro día a día. Empecemos:
Contract o contrato
El contrato es básicamente la específicación de como se de debe hacer la petición y como va a responder este según la manera en la que se arma la petición. (Esencial para hacer contract testing)
cURL
La definición oficial: es una herramienta de línea de comandos, que permite transferir datos hacia o desde un servidor sin interacción del usuario.
En la actualidad es un estandar para compartir una petición que estamos realizando, ya sea desde el navegador o de alguna herramienta para diseño/prueba y prueba de APIs. Para entender mejor como se construye un cURL les recomiendo visitar Curl Builder
Endpoint
Los endpoints son en pocas palabras el medio con lo que accedemos o interactuamos con la API aunque es normal al momento de hablar de endpoint mencionar solo la path de este, ejemplo: si tenemos http://localhost/user/info , diríamos: El que falla es el user info , cada endpoint es la url + metodo + data disponible que utilizamos para hacer alguna acción sobre el servidor.
Header
Los headers tienen una definición un poco compleja y para entender esto al 100% debemos hablar de redes (y soy bastante ignorante en esta materia), voy a tratar de simplificar el concepto.
Debemos saber que podemos tener cabeceras de petición y de respuesta.
Ya con esto podemos decir que en las cabeceras de petición, lo utilizamos para proporcionar al servidor información adicional o complementaria del tipo de petición que estamos realizando.
La cabecera de petición más común es el Content-Type que lo utilizamos para indicar el formato de texto a utilizar en el payload (definido más abajo), esto se conforma por un par llave-valor por lo que la definición completa de esta cabecera sería Content-Type:application/json
Otra cabecera muy común es Authorization utilizada para agregar un token.
En la industria también se ha creado un estandar para utilizar cabeceras customizadas y estas tienden a iniciar con una letra equis (x) aunque no es obligario, ejemplo: X-Api-Key
Existen palabras reservadas o cabeceras pre-definidas y justo cuando una cabcera custom coincide con el nombre de una de las pre-definidas es cuando entra en juego el usar la X. Les comparto el listado completo de cabeceras por si quieren darle una mirada: List of all HTTP headers
Path param
Path param (parámetros de ruta) son básicamente variables de solicitud que se agregan a la url para indicar que queremos acceder a un recurso específico. No existe un posición específica en la que deba estar, aunque es muy común que al momento de crear la definición del endpoint se agregue al final de la ruta, ejemplo: /user/1234 , a nivel de código encontraremos algo así /user/:userId
Otro ejemplo que puedo mostrarles: /client/:clientId/department/:departmentId/employees
Payload o Request Body
En el contexto de APIs, payload o request body hace referencia a los datos que van a ser enviados en una petición. En esencia el conetenido de un mensaje que será enviado entre un cliente y un servidor. La mayoría de las APIs implementan JSON como formato pero hay que ser consciente que no es el único, también existen XML, Raw text y Plain text. (Desconozco si existen otros formatos. Si conocen algún otro lo pueden dejar en los comentarios y lo agrego y así habilitamos de alguna manera el modo colaborativo).
Query param
A diferencia de los parámetros de ruta, los parámetros de consultas son fáciles de identificar: se colocan al final de la url, viene después del signo de interrogación (?) y se utiliza bajo la premisa de llave-valor.
Estos parámetros tienen en defición una funcionalidad específica: filtrar la respuesta, un caso de uso común sería seleccionar los usuarios que solo estén con status pendiente, ejemplo: /users?status=pending
Se pueden utilizar cuanto parámetros sean necesarios para ser lo más específico en lo que deseamos obtener como respuesta, y para poder agregar más parámetros tan solo debemos agregar un ampersand(&), ejemplo: /users?status=pending&sort=desc
Dato extra: también existe matrix param aunque la utilización es casi nula, siempre suma el saber de su existencia.
Request
Bastante sencillo, es la petición en si. Podemos decir que al utilizar un cURL estamos creando una petición.
Para desglozar un poco, podemos decir que una request se compone por: un método, una url, cabeceras y payload
Response
Al igual que request, la definición es muy sencilla. Es la respuesta a una petición. Esta respuesta se compone por: cabeceras de respuesta, un código de estatus y un cuerpo de respuesta (si aplica)
Como describo en el título las deficiones presentadas son solamente aquellas que vamos a estar utilizando en el día a día, obviamente nos faltan muchas definiciones por lo que les comparto para búsqueda otras que son importantes de conocer:
- API
- Rest
- API Rest
- API Rest full
- URI
- Métodos o Verbos HTTP
- HTTP
- Signature (hmac)
Con esto hemos finalizado lo que podríamos llamar la introducción a APIs, en la siguiente publicación hablaremos sobre las buenas prácticas para construcción de una Api Rest que nosotros como probadores debemos conocer, ya que también es parte de nuestra labor poder participar en la definición de los endpoints.
Esta lista ha sido corta pero con saber esto ya tenemos medio camino cruzado.
¿Consideras qué hay alguna otra definición que debamos agregar? Comentala y actualizo!
Top comments (2)
buena serie, esperando la 3
yo sí añadiría un párrafo explicando la intención de los verbos HTTP (al menos explicando get, post y delete). Creo que viene muy al caso de este post aunque seguramente lo tratarás más adelante
Si, tenía intención mencionarla más adelante pero creo que tiene mucho sentido en las definiciones esenciales mencionar eso.
Lo agrego, muchas gracias por comentar!!!!