API - Documentación¶
PhotoILike proporciona un servizo de API REST que permite ás compañías integrar os servizos nos seus propios sistemas. Nesta documentación atopará as instrucións necesarias para que esta integración se realice da forma máis sinxela posible. Se aínda así ten algunha dúbida ou problema, non dubide en contactar connosco a través desta ligazón.
Client-key¶
Para os clientes finais, PhotoILike dispón dun Software as a Service en https://app.photoilike.com. Con todo, as empresas que requiran dar soporte a varios clientes, poden integrar os nosos servizos dentro das súas propias implementacións.
PhotoILike proporciona unha maneira directa de traballar con múltiples usuarios a través de client-keys, tendo cada usuario final un client-key único. PhotoILike permite crear tantos client-keys como sexan necesarios e estes deben ser utilizados para cada un dos recursos que se soliciten.
Cantidade máxima de peticións simultáneas¶
A maioría das peticións que se poden realizar ao API de PhotoILike deben ir acompañadas dun client-key e teñen un límite por segundo. A seguinte táboa mostra a cantidade máxima de peticións por segundo que se poden realizar por client-key.
| Recurso | Límite |
|---|---|
score |
5/sg |
label |
5/sg |
sort |
10/sg |
O resto de peticións non teñen por que ir acompañadas dun client-key, pero tamén teñen un límite por segundo. A seguinte táboa mostra a cantidade de peticións que se poden realizar neses casos.
| Recurso | Limite |
|---|---|
client key |
5/sg |
Código de erros¶
Utilízanse os código HTTP para definir os erros dunha petición que non se resolve de forma satisfactoria. A continuación móstranse os distintos tipos de erros que se poden producir ao utilizar nosa API, aínda que se ten algunha dúbida sempre pode contactar co equipo de PhotoILike a través desta ligazón.
Erros no lado do cliente¶
| Código HTTP | Significado |
|---|---|
400 |
Petición incorrecta. Este erro adoita aparecer cando un parámetro que se introduciu non é correcto, introducíronse parámetros non esperados ou falta algún parámetro por introducir. |
401 |
Non se autenticou correctamente. |
402 |
Esgotáronse todos os créditos dispoñibles. |
403 |
Non dispón dos permisos adecuados para poder levar a cabo a petición solicitada. |
404 |
Non se atopa o recurso solicitado. |
405 |
O método solicitado non está dispoñible. |
408 |
A url da que se tenta obter o recurso para procesar tarda demasiado tempo. |
411 |
O servidor que contén a imaxe para procesar non devolve información sobre o seu tamaño. |
413 |
A petición solicitada ten un tamaño moi grande. |
415 |
O formato no que se enviou a petición non está soportado. |
429 |
Realizáronse moitas peticións consecutivas. Os parámetros X-RateLimit nas cabeceiras indican o estado actual das peticións. |
Erros no lado do servidor¶
Desde PhotoILike traballamos duro para que non se produza ningún erro nos nosos servidores, pero por razóns que escapan ao noso control poderíase producir algún dos seguintes:
| Código HTTP | Significado |
|---|---|
500 |
Produciuse un erro interno no servidor e non puido procesar a petición. |
502 |
O acceso aos servizos está a configurarse e aínda non está dispoñible. |
503 |
O servizo non está dispoñible nese momento. |
504 |
El servidor esta tardando más tiempo del esperado en resolver la petición. |
Recomendacións¶
Numerosos compoñentes dunha rede, como os servidores DNS, os conmutadores ou os balanceadores de carga, entre outros, poden xerar erros en calquera punto da vida dunha solicitude determinada. A técnica habitual para abordar estas respostas de erro nunha contorna de rede consiste é implementar os reintentos na aplicación cliente. Esta técnica aumenta a fiabilidade da aplicación e reduce os custos operativos para o desarrollador.
Por ese motivo é necesario que ao usar calquera API, sexa de PhotoILike ou calquera outra, se reintenten as solicitudes orixinais que reciban erros de servidor (5xx) ou limitación. Con todo, os erros de cliente (4xx)1 indican que é preciso revisar a solicitude para corrixir o problema antes de reintentar a petición.
Unha forma sinxela de realizar os intentos é a utilización de algoritmos de backoff exponencial e jitter para os que existen implementacións dispoñibles para varias linguaxes2.
-
Ante os erros 408 e 429 pódese reintentar a petición porque poden ser un fallo temporal. No exemplo do erro 408 é debido a que a URL desde a que se tenta obter a imaxe tarda moito tempo en responder o que indica que pode estar saturado nun instante determinado e que máis adiante no tempo non estea saturada e responda con normalidade. En canto ao erro 429, débese a que se están facendo moitas peticións simultáneas, o que por definición indica que nun breve período de tempo pódense volver realizar peticións. ↩
-
Algunhas librarías dispoñibles coa implementación: