L'API est utilisée pour s'intégrer aux systèmes Digital Asset Management, à la gestion des utilisateurs et à bien d'autres. Le Showpad API Explorer vous permet d'essayer l' API et vous pouvez y accéder via la Online Platform dans les paramètres administrateur. Cet article va plus profondément dans le monde de l'API Showpad et explique les différentes méthodes et paramètres que vous pouvez utiliser.
Remarque : pour accéder directement à l'API Explorer, accédez à https : // {votresomaine}.Showpad.biz / devportal / explorer
Principales caractéristiques
L'API Showpad est une API client-serveur de RESTful. Essentiellement, le terme REST est utilisé pour indiquer que l'API est basée sur les principes de :
- Envoi d'une requête HTTP et réception d'une réponse HTTP
- Utiliser les verbes HTTP (GET, POST, PUT...)
- Interprétation des codes de réponse HTTP
- Ressources
Remarque : L'URL de base de l'API REST est / API / v {apiVersion}.
Ce qu'il vous faut pour réussir
Voici ce dont vous avez besoin pour créer votre première application qui s'interface avec l'API REST Showpad:
- Plan tarifaire ultime de Showpad
- Accès à Showpad Online Platform
- Connaissance de base de REST
- Connaissance de base de JSON
- Emplacement de ressource universel (URL)
- Ressources et liens de ressources
- Méthodes HTTP
- Demander des en-têtes
- Types de médias
- Paramètres de requête
- En-têtes de réponse
- Codes de réponse HTTP
Emplacement de ressource universel (URL)
L'URL identifie la ressource ou la Collection de liens de ressources à laquelle vous souhaitez accéder. Il est structuré comme suit :
/API/ v {apiVersion} / {ressource} [/ {resourceId} [/ {sous-ressource}]] [.JSON] |
Voici quelques exemples :
- /API/v1/tags.JSON
- / API / v2 / assets /12345.JSON
- / API / v2 / users /12345/usergroups.JSON
Ressources et liens de ressources
Une réponse de l'API Showpad est basée sur le concept de ressources et de liens de ressources. Une ressource est l'entité centrale de l'API Showpad. Il se caractérise par un identifiant, un type, un ensemble d'attributs et un ensemble de relations avec d'autres ressources.
"réponse" : { "id" : "279386a847eb5802fc566cb773916d41", "resourcetype" : "Asset", "name" : "Showpad One Pager.pdf", .... étiquettes "href"https://demo.showpad.biz/api/v3/assets/279386afc566cb773916d41/tags"RL-0 }, "division" : { "id"4643adcc1621814e91c489b34bb428edID-1", "href"https://demo.showpad.biz/api/v3/divisions/4643ae91c489b34bb428ed"RL-1 }, |
Une caractéristique importante de la ressource est son type, identifié par le type de champ. Chaque ressource possède ce champ et il existe 12 types de ressources, distribués à la fois sur le revendeur et sur l'API de la société.
Type de ressource | Disponibilité | Type |
---|---|---|
Clé API | V1 | Revendeur + Société |
Atout | V1 + | Revendeur + Société |
Commentaire | V1 + | Revendeur + Société |
Contentprofile | V2 + | Nom de l'entreprise |
Division | V2 + | Nom de l'entreprise |
DivisionPermission | V2 + | Nom de l'entreprise |
Organisation | V1 + | Revendeur |
TabletPermission | V2 + | Revendeur |
Étiquette | V1 + | Revendeur |
Billet | V1 + | Nom de l'entreprise |
Groupe d'utilisateurs | V1 + | Nom de l'entreprise |
Utilisateur | V1 + | Nom de l'entreprise |
Dans une configuration d'API REST de base, une requête HTTP est envoyée au serveur Showpad, qui la traite et répond avec une réponse HTTP. La demande elle-même comporte un certain nombre de paramètres importants pour l'API Showpad. Il prend en charge les méthodes HTTP suivantes pour mapper les opérations CRUD (créer, récupérer, mettre à jour, supprimer) aux demandes HTTP. En plus de cela, l'API Showpad prend également en charge les méthodes LINK AND UNLINK pour créer et supprimer des relations entre les ressources :
Remarque : Les utilisateurs n'ont pas accès à tous les actifs à l'aide de l'API REST.
Méthode |
Description |
---|---|
OBTENIR |
Utilisé pour récupérer les ressources d'une Collection de liens de ressources |
POSTER |
Utilisé pour créer ou mettre à jour une ressource |
METTRE |
Utilisé pour mettre à jour une ressource |
EFFACER |
Utilisé pour supprimer une ressource |
LINK |
Utilisé pour établir une relation entre les ressources |
UNLINK |
Utilisé pour rompre une relation établie entre les ressources |
TÊTE |
Utilisé pour récupérer les ressources d'une Collection de liens de ressources |
Les paramètres d'en-tête sont des paramètres attachés à l'en-tête de la demande. Outre les paramètres d'en-tête standard tels que Content-Type, il existe certains paramètres d'en-tête spécialement conçus pour être utilisés dans l'API Showpad.
Paramètre | Type | Version | Description | |||
---|---|---|---|---|---|---|
SHOWPADAUTHORIZATIONKEY |
|
Toutes les demandes authentifiées | V1 |
Chaque demande nécessitant une authentification nécessite que cet en-tête soit définie. Elle contient la clé d'API Showpad. Applicable uniquement dans API V1. |
||
AUTORISATION |
|
Toutes les demandes authentifiées | V2 |
Utilisé pour les demandes authentifiées OAuth2. Il contient le jeton d'accès OAuth2 au format suivant : AUTORISATION : Porteur :myObtainedAccessToken Applicable uniquement dans API V2. |
||
LINK |
Demandes LINK, UNLINK et POST (créer une ressource) | V1 + |
Vous pouvez spécifier quelles ressources doivent être liées / non liées à la ressource en question en ajoutant un paramètre à la demande. Une relation est spécifiée comme suit : LINK : <ID_ressource> ; rel = "RelatedResourceType" L'utilisation de ce paramètre est basée sur le projet de norme IETF. Vous pouvez ajouter plusieurs relations en délimitant ce paramètre par une virgule. Par exemple : LIEN : <ID1> ; rel = "RelatedResourceType1", <ID2> ; rel = "RelatedResourceType2", <ID3> ; rel = "RelatedResourceType3" |
|||
X-HTTP-METHOD-OVERRIDE |
|
Ressource GET Collection (par exemple / users) ou des demandes de ressources GET (par exemple / users / {id} ) |
Certains clients API rencontrent des difficultés pour envoyer des requêtes avec certains verbes HTTP tels que PUT ou LINK. Afin de rendre ces demandes possibles, le paramètre X-HTTP-METHOD-OVERRIDE peut être utilisé pour imiter une certaine méthode HTTP, tout en conservant les mêmes paramètres. Par exemple : X-HTTP-METHOD-OVERRIDE : supprimer |
Afin de POST ou PUT des données à Showpad, 3 types de contenu différents peuvent être utilisés.
Nom du champ d'en-tête | Description |
---|---|
Type de contenu | application / www-url-encoded (PUT + POST) |
multipart / form-data (POST uniquement) | |
application / JSON (PUT + POST) |
Notes :
- Application / www-url-encoded et multipart / form-data ne peuvent être utilisés que pour ajouter ou mettre à jour une ressource unique.
- Sachez que multipart / form-data n'est valide que pour les requêtes POST.
- Application / JSON peut être utilisé à la fois pour mettre à jour une ressource et créer une ou plusieurs ressources.
- Pour créer une seule ressource, vous utilisez un tableau de valeurs de clé JSON, tandis que lorsque vous souhaitez créer plusieurs ressources par lots, vous utilisez un tableau de tableaux de valeurs de clés JSON.
Les paramètres de requête sont des paramètres attachés à l'URL, généralement après le Parcours de l'URL et encodés sous la forme application / x-www-form-urlencoded. L'exemple ci-dessous montre 3 paramètres : limite et offset.
Selon le type de demande, il existe un certain nombre de paramètres de requête standard :
Paramètre | Type | Disponibilité | Description | |||
---|---|---|---|---|---|---|
limite | Collection GET ResourceLink | V1 + | Limite le nombre de liens de ressources récupérés, c’est-à-dire qu'une limite de 25 renverra 25 liens de ressources. | |||
décalage | Collection GET ResourceLink | V1 + | Décalage des liens de ressources récupérés, c’est-à-dire qu'un décalage de 3 ignore les 3 premiers résultats. | |||
des champs | GET Resource ou GET ResourceLink Collection | V1 + | Liste d'attributs séparés par des virgules à renvoyer dans la réponse. Est généralement utilisé pour alléger la réponse. Par exemple, si vous souhaitez uniquement connaître l'ID des ressources d'une Collection, spécifier "id" en tant que paramètre de champ extrairait uniquement une Collection d'identificateurs. | |||
méthode | GET Resource ou GET ResourceLink Collection | V1 + | Certains clients API rencontrent des difficultés pour envoyer des requêtes avec certains verbes HTTP tels que PUT ou LINK. Afin de rendre ces demandes possibles, le paramètre 'méthode' peut être utilisé pour imiter une certaine méthode HTTP, tout en conservant les mêmes paramètres. | |||
décris_modèle | Toutes les demandes | V1 + | Ajoute la spécification de modèle Swagger à la demande | |||
décrire_apis | Toutes les demandes | V1 + | Ajoute la description de l'API Showpad à la demande. | |||
suppress_response_codes | Toutes les demandes | V1 + | Certains clients API ont leur propre manière de traiter les codes de réponse HTTP. Par exemple, certains clients lèvent une exception lorsqu'ils reçoivent 40x sur 50x, ne laissant aucun moyen de contrôler le contenu de la réponse. Si vous définissez 'suppress_response_codes' sur true, tous les codes de réponse HTTP ont la valeur 200, ce qui facilite l'inspection des réponses. Dans le champ 'méta' de la réponse, le code de réponse d'origine est toujours mentionné afin qu'une interprétation correcte puisse toujours avoir lieu. |
Le nombre total de correspondances correspondant à votre demande peut être trouvé dans l'attribut « nombre ».
" réponse " : { " compter " : 29, articles } |
Les champs d'en-tête suivants sont envoyés pour chaque demande.
Nom du champ d'en-tête |
Description |
---|---|
accès-contrôle-autoriser-informations d'identification |
Spécifie quels emplacements peuvent participer au partage de ressources entre origines |
accès-contrôle-autoriser les en-têtes |
Spécifie quels emplacements peuvent participer au partage de ressources entre origines |
méthodes de contrôle d'accès |
Spécifie quels emplacements peuvent participer au partage de ressources entre origines |
accès-contrôle-autoriser-origine |
Spécifie quels emplacements peuvent participer au partage de ressources entre origines |
contrôle de cache |
Instructions de mise en cache pour le serveur. |
lien |
Options de contrôle pour la connexion en cours |
codage du contenu |
Le type d'encodage utilisé sur les données, généralement 'gzip' |
type de contenu |
Le type de média de ce contenu, typiquement 'application / JSON' |
rendez-vous amoureux | Date et heure d'envoi du message par le serveur |
pragma | Instruction de mise en cache pour le serveur, mais pour le client HTTP / 1.0 |
serveur | Nom du serveur |
transfert-encodage | Forme d'encodage utilisée pour transférer l'entité à l'utilisateur en toute sécurité, généralement "chunked" |
x-content-type-options | Typiquement 'nosniff' |
x-frame-options | |
x-newrelic-app-data | |
limite x ratelimit | Nombre de demandes autorisées par jour |
x-ratelimit-restante | Nombre de demandes restantes |
x-ratelimit-reset | Horodatage de la date à laquelle votre limite de taux sera réinitialisée |
x-robots-tag | |
x-xss-protection |
Code | Nom | Description | Exemple |
---|---|---|---|
200 | OK | Renvoyé lorsqu'une demande est exécutée avec succès | GET /users.JSON renverra une Collection de liens utilisateur |
201 | Créé | Renvoyé quand une ressource est créée | POST /users.JSON (si les données saisies étaient correctes) |
400 | Mauvaise Demande | Renvoyé lorsque la demande est invalide. C'est une erreur très générale. | |
401 | Non autorisé | Renvoyé lorsqu'un jeton d'accès incorrect a été spécifié | Un jeton d'accès OAuth2 incorrect ou expiré a été envoyé. |
403 | Interdit | Renvoyé lorsque l'utilisateur ne dispose pas d'autorisations suffisantes pour accéder à la ressource. | Les divisions sont uniquement accessibles aux sociétés activées par la division |
404 | Pas trouvé | Renvoyé lorsqu'une ressource n'est pas trouvée. | Spécifier un ID inexistant est spécifié. |
405 | Méthode introuvable | Renvoyé lorsqu'une méthode HTTP non valide est utilisée. | POST /tickets.JSON n'est pas pris en charge |
409 | Conflit | Renvoyé lorsque l'utilisateur a entré des données non valides. | Création d'un utilisateur avec un nom d'utilisateur non unique |
429 | Trop de demandes | Renvoyé lorsque l'utilisateur dépasse la limite de débit pour une période donnée. | |
500 | Erreur Interne du Serveur | Renvoyé lorsqu'une erreur de serveur se produit. |