Intégration Protocols.io

Présentation

Protocols.io est une plateforme complète pour développer, partager et gérer des protocoles scientifiques. Cette skill fournit une intégration complète avec l'API protocols.io v3, permettant un accès programmatique aux protocoles, espaces de travail, discussions, gestion de fichiers et fonctionnalités de collaboration.

Quand utiliser cette skill

Utilisez cette skill lorsque vous travaillez avec protocols.io dans les scénarios suivants :

• Découverte de protocoles : Rechercher des protocoles existants par mots-clés, DOI ou catégorie
• Gestion de protocoles : Créer, mettre à jour ou publier des protocoles scientifiques
• Gestion des étapes : Ajouter, modifier ou organiser les étapes et procédures des protocoles
• Développement collaboratif : Travailler avec des membres d'équipe sur des protocoles partagés
• Organisation des espaces de travail : Gérer les référentiels de protocoles de laboratoire ou institutionnels
• Discussion et retours : Ajouter ou répondre à des commentaires sur les protocoles
• Gestion de fichiers : Télécharger des fichiers de données, images ou documents vers des protocoles
• Suivi des expériences : Documenter les exécutions et résultats des protocoles
• Export de données : Sauvegarder ou migrer des collections de protocoles
• Projets d'intégration : Construire des outils qui interagissent avec protocols.io

Capacités principales

Cette skill fournit des conseils complets dans cinq domaines de capacité majeurs :

1. Authentification et accès

Gérez l'authentification de l'API à l'aide de jetons d'accès et de flux OAuth. Inclut à la fois les jetons d'accès client (pour le contenu personnel) et les jetons OAuth (pour les applications multi-utilisateurs).

Opérations clés :

• Générer des liens d'autorisation pour le flux OAuth
• Échanger les codes d'autorisation contre des jetons d'accès
• Actualiser les jetons expirés
• Gérer les limites de débit et les autorisations

Référence : Lisez references/authentication.md pour les procédures d'authentification détaillées, l'implémentation OAuth et les meilleures pratiques de sécurité.

2. Opérations sur les protocoles

Gestion complète du cycle de vie des protocoles de la création à la publication.

Opérations clés :

• Rechercher et découvrir des protocoles par mots-clés, filtres ou DOI
• Récupérer les informations détaillées du protocole avec toutes les étapes
• Créer de nouveaux protocoles avec métadonnées et balises
• Mettre à jour les informations et paramètres du protocole
• Gérer les étapes du protocole (créer, mettre à jour, supprimer, réorganiser)
• Gérer les matériaux et réactifs du protocole
• Publier les protocoles avec émission de DOI
• Marquer les protocoles en favori pour un accès rapide
• Générer des PDF de protocoles

Référence : Lisez references/protocols_api.md pour les conseils complets de gestion des protocoles, y compris les points de terminaison API, les paramètres, les flux de travail courants et des exemples.

3. Discussions et collaboration

Permettez l'engagement communautaire par le biais de commentaires et de discussions.

Opérations clés :

• Afficher les commentaires au niveau du protocole et de l'étape
• Créer de nouveaux commentaires et réponses enfilées
• Modifier ou supprimer vos propres commentaires
• Analyser les modèles de discussion et les retours
• Répondre aux questions et problèmes des utilisateurs

Référence : Lisez references/discussions.md pour la gestion des discussions, l'enfilage des commentaires et les flux de travail de collaboration.

4. Gestion des espaces de travail

Organisez les protocoles dans des espaces de travail d'équipe avec des autorisations basées sur les rôles.

Opérations clés :

• Lister et accéder aux espaces de travail des utilisateurs
• Récupérer les détails de l'espace de travail et les listes de membres
• Demander l'accès ou rejoindre les espaces de travail
• Lister les protocoles spécifiques à l'espace de travail
• Créer des protocoles dans les espaces de travail
• Gérer les autorisations et la collaboration des espaces de travail

Référence : Lisez references/workspaces.md pour l'organisation des espaces de travail, la gestion des autorisations et les modèles de collaboration en équipe.

5. Opérations sur les fichiers

Téléchargez, organisez et gérez les fichiers associés aux protocoles.

Opérations clés :

• Rechercher les fichiers et dossiers de l'espace de travail
• Télécharger des fichiers avec métadonnées et balises
• Télécharger les fichiers et vérifier les téléchargements
• Organiser les fichiers dans des hiérarchies de dossiers
• Mettre à jour les métadonnées des fichiers
• Supprimer et restaurer les fichiers
• Gérer le stockage et l'organisation

Référence : Lisez references/file_manager.md pour les procédures de téléchargement de fichiers, les stratégies d'organisation et la gestion du stockage.

6. Fonctionnalités supplémentaires

Fonctionnalité supplémentaire incluant les profils, les notifications et les exports.

Opérations clés :

• Gérer les profils utilisateur et les paramètres
• Interroger les protocoles récemment publiés
• Créer et suivre les enregistrements d'expériences
• Recevoir et gérer les notifications
• Exporter les données organisationnelles pour archivage

Référence : Lisez references/additional_features.md pour la gestion des profils, la découverte de publications, le suivi des expériences et l'export de données.

Démarrage

Étape 1 : Configuration de l'authentification

Avant d'utiliser une fonctionnalité de l'API protocols.io :

1. Obtenir un jeton d'accès (CLIENT_ACCESS_TOKEN ou OAUTH_ACCESS_TOKEN)
2. Lire references/authentication.md pour les procédures d'authentification détaillées
3. Stocker le jeton de manière sécurisée
4. Inclure dans toutes les demandes comme : Authorization: Bearer YOUR_TOKEN

Étape 2 : Identifiez votre cas d'usage

Déterminez quel domaine de capacité répond à vos besoins :

• Travailler avec des protocoles ? → Lire references/protocols_api.md
• Gérer les protocoles d'équipe ? → Lire references/workspaces.md
• Traiter les commentaires/retours ? → Lire references/discussions.md
• Télécharger des fichiers/données ? → Lire references/file_manager.md
• Suivi des expériences ou des profils ? → Lire references/additional_features.md

Étape 3 : Implémentez l'intégration

Suivez les conseils dans les fichiers de référence appropriés :

• Chaque référence inclut la documentation détaillée des points de terminaison
• Les paramètres API et les formats de demande/réponse sont spécifiés
• Les cas d'usage courants et les flux de travail sont fournis avec des exemples
• Les conseils sur les meilleures pratiques et la gestion des erreurs sont inclus

URL de base et format de demande

Toutes les demandes API utilisent l'URL de base :

https://protocols.io/api/v3

Toutes les demandes nécessitent l'en-tête d'autorisation :

Authorization: Bearer YOUR_ACCESS_TOKEN

La plupart des points de terminaison supportent le format de demande/réponse JSON avec Content-Type: application/json.

Options de format de contenu

De nombreux points de terminaison supportent un paramètre content_format pour contrôler comment le contenu du protocole est retourné :

• json : Format JSON Draft.js (par défaut)
• html : Format HTML
• markdown : Format Markdown

Inclure en tant que paramètre de requête : ?content_format=html

Limitation du débit

Soyez conscient des limites de débit de l'API :

• Points de terminaison standard : 100 demandes par minute par utilisateur
• Point de terminaison PDF : 5 demandes/minute (connecté), 3 demandes/minute (non connecté)

Implémentez une backoff exponentielle pour les erreurs de limite de débit (HTTP 429).

Flux de travail courants

Flux de travail 1 : Importer et analyser un protocole

Pour analyser un protocole existant de protocols.io :

1. Rechercher : Utiliser GET /protocols avec des mots-clés pour trouver les protocoles pertinents
2. Récupérer : Obtenir les détails complets avec GET /protocols/{protocol_id}
3. Extraire : Analyser les étapes, matériaux et métadonnées
4. Examiner les discussions : Vérifier GET /protocols/{id}/comments pour les retours des utilisateurs
5. Exporter : Générer un PDF si nécessaire pour une référence hors ligne

Fichiers de référence : protocols_api.md, discussions.md

Flux de travail 2 : Créer et publier un protocole

Pour créer un nouveau protocole et le publier avec un DOI :

1. Authentifier : Assurez-vous d'avoir un jeton d'accès valide (voir authentication.md)
2. Créer : Utiliser POST /protocols avec titre et description
3. Ajouter des étapes : Pour chaque étape, utiliser POST /protocols/{id}/steps
4. Ajouter des matériaux : Documenter les réactifs dans les composants d'étape
5. Examiner : Vérifier que tout le contenu est complet et exact
6. Publier : Émettre un DOI avec POST /protocols/{id}/publish

Fichiers de référence : protocols_api.md, authentication.md

Flux de travail 3 : Espace de travail de laboratoire collaboratif

Pour mettre en place la gestion des protocoles d'équipe :

1. Créer/rejoindre un espace de travail : Accéder ou demander l'adhésion à l'espace de travail (voir workspaces.md)
2. Organiser la structure : Créer une hiérarchie de dossiers pour les protocoles de laboratoire (voir file_manager.md)
3. Créer des protocoles : Utiliser POST /workspaces/{id}/protocols pour les protocoles d'équipe
4. Télécharger des fichiers : Ajouter des données expérimentales et des images
5. Activer les discussions : Les membres de l'équipe peuvent commenter et fournir des retours
6. Suivre les expériences : Documenter les exécutions de protocoles avec des enregistrements d'expériences

Fichiers de référence : workspaces.md, file_manager.md, protocols_api.md, discussions.md, additional_features.md

Flux de travail 4 : Documentation des expériences

Pour suivre les exécutions et les résultats des protocoles :

1. Exécuter le protocole : Effectuer le protocole en laboratoire
2. Télécharger les données : Utiliser l'API Gestionnaire de fichiers pour télécharger les résultats (voir file_manager.md)
3. Créer un enregistrement : Documenter l'exécution avec POST /protocols/{id}/runs
4. Lier les fichiers : Référencer les fichiers de données téléchargés dans l'enregistrement d'expérience
5. Noter les modifications : Documenter les écarts ou optimisations du protocole
6. Analyser : Examiner plusieurs exécutions pour évaluer la reproductibilité

Fichiers de référence : additional_features.md, file_manager.md, protocols_api.md

Flux de travail 5 : Découverte et citation de protocoles

Pour trouver et citer des protocoles dans la recherche :

1. Rechercher : Interroger les protocoles publiés avec GET /publications
2. Filtrer : Utiliser les filtres de catégorie et de mots-clés pour les protocoles pertinents
3. Examiner : Lire les détails du protocole et les commentaires de la communauté
4. Marquer en favori : Enregistrer les protocoles utiles avec POST /protocols/{id}/bookmarks
5. Citer : Utiliser le DOI du protocole dans les publications (attribution appropriée)
6. Exporter en PDF : Générer un PDF formaté pour une référence hors ligne

Fichiers de référence : protocols_api.md, additional_features.md

Exemples de demandes Python

Recherche basique de protocole

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}

# Rechercher des protocoles CRISPR
response = requests.get(
    "https://protocols.io/api/v3/protocols",
    headers=headers,
    params={
        "filter": "public",
        "key": "CRISPR",
        "page_size": 10,
        "content_format": "html"
    }
)

protocols = response.json()
for protocol in protocols["items"]:
    print(f"{protocol['title']} - {protocol['doi']}")

Créer un nouveau protocole

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Créer un protocole
data = {
    "title": "CRISPR-Cas9 Gene Editing Protocol",
    "description": "Comprehensive protocol for CRISPR gene editing",
    "tags": ["CRISPR", "gene editing", "molecular biology"]
}

response = requests.post(
    "https://protocols.io/api/v3/protocols",
    headers=headers,
    json=data
)

protocol_id = response.json()["item"]["id"]
print(f"Created protocol: {protocol_id}")

Télécharger un fichier dans un espace de travail

import requests

token = "YOUR_ACCESS_TOKEN"
headers = {"Authorization": f"Bearer {token}"}

# Télécharger un fichier
with open("data.csv", "rb") as f:
    files = {"file": f}
    data = {
        "folder_id": "root",
        "description": "Experimental results",
        "tags": "experiment,data,2025"
    }

    response = requests.post(
        "https://protocols.io/api/v3/workspaces/12345/files/upload",
        headers=headers,
        files=files,
        data=data
    )

file_id = response.json()["item"]["id"]
print(f"Uploaded file: {file_id}")

Gestion des erreurs

Implémentez une gestion robuste des erreurs pour les demandes API :

import requests
import time

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:  # Rate limit
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:  # Server error
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                response.raise_for_status()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")

Fichiers de référence

Chargez le fichier de référence approprié en fonction de votre tâche :

• authentication.md : Flux OAuth, gestion des jetons, limitation du débit
• protocols_api.md : Protocoles CRUD, étapes, matériaux, publication, PDFs
• discussions.md : Commentaires, réponses, collaboration
• workspaces.md : Espaces de travail d'équipe, autorisations, organisation
• file_manager.md : Téléchargement de fichiers, dossiers, gestion du stockage
• additional_features.md : Profils, publications, expériences, notifications

Pour charger un fichier de référence, lisez le fichier à partir du répertoire references/ si nécessaire pour une fonctionnalité spécifique.

Meilleures pratiques

1. Authentification : Stockez les jetons de manière sécurisée, jamais dans le code ou le contrôle de version
2. Limitation du débit : Implémentez la backoff exponentielle et respectez les limites de débit
3. Gestion des erreurs : Traitez tous les codes d'erreur HTTP de manière appropriée
4. Validation des données : Validez l'entrée avant les appels API
5. Documentation : Documentez les étapes du protocole en détail
6. Collaboration : Utilisez les commentaires et les discussions pour la communication d'équipe
7. Organisation : Maintenez des conventions cohérentes de nommage et de balisage
8. Versioning : Suivez les versions des protocoles lors des mises à jour
9. Attribution : Citez correctement les protocoles en utilisant les DOIs
10. Sauvegarde : Exportez régulièrement les protocoles importants et les données de l'espace de travail

Ressources supplémentaires

• Documentation officielle de l'API : https://apidoc.protocols.io/
• Plateforme Protocols.io : https://www.protocols.io/
• Support : Contactez le support de protocols.io pour l'accès à l'API et les problèmes techniques
• Communauté : Participez à la communauté protocols.io pour les meilleures pratiques

Dépannage

Problèmes d'authentification :

• Vérifiez que le jeton est valide et non expiré
• Vérifiez le format de l'en-tête d'autorisation : Bearer YOUR_TOKEN
• Assurez-vous du type de jeton approprié (CLIENT ou OAUTH)

Limitation du débit :

• Implémentez la backoff exponentielle pour les erreurs 429
• Surveillez la fréquence des demandes
• Envisagez de mettre en cache les demandes fréquentes

Erreurs de permission :

• Vérifiez les autorisations d'accès à l'espace de travail/protocole
• Vérifiez le rôle de l'utilisateur dans l'espace de travail
• Assurez-vous que le protocole n'est pas privé si vous y accédez sans permission

Échecs de téléchargement de fichiers :

• Vérifiez la taille du fichier par rapport aux limites de l'espace de travail
• Vérifiez que le type de fichier est supporté
• Assurez-vous que l'encodage multipart/form-data est correct

Pour des conseils détaillés de dépannage, reportez-vous aux fichiers de référence spécifiques couvrant chaque domaine de capacité.