Protocolsio Integration

Integração Protocols.io

Visão Geral

Protocols.io é uma plataforma abrangente para desenvolver, compartilhar e gerenciar protocolos científicos. Esta skill oferece integração completa com a API v3 protocols.io, permitindo acesso programático a protocolos, espaços de trabalho, discussões, gerenciamento de arquivos e recursos de colaboração.

Quando Usar Esta Skill

Use esta skill ao trabalhar com protocols.io em qualquer um dos seguintes cenários:

• Descoberta de Protocolo: Pesquisar protocolos existentes por palavras-chave, DOI ou categoria
• Gerenciamento de Protocolo: Criar, atualizar ou publicar protocolos científicos
• Gerenciamento de Etapas: Adicionar, editar ou organizar etapas e procedimentos de protocolo
• Desenvolvimento Colaborativo: Trabalhar com membros da equipe em protocolos compartilhados
• Organização do Espaço de Trabalho: Gerenciar repositórios de protocolo de laboratório ou institucionais
• Discussão e Feedback: Adicionar ou responder comentários de protocolo
• Gerenciamento de Arquivos: Fazer upload de arquivos de dados, imagens ou documentos para protocolos
• Rastreamento de Experimentos: Documentar execuções de protocolo e resultados
• Exportação de Dados: Fazer backup ou migrar coleções de protocolo
• Projetos de Integração: Criar ferramentas que interagem com protocols.io

Capacidades Principais

Esta skill oferece orientação abrangente em cinco áreas principais de capacidade:

1. Autenticação e Acesso

Gerenciar autenticação de API usando tokens de acesso e fluxos OAuth. Inclui tanto tokens de acesso do cliente (para conteúdo pessoal) quanto tokens OAuth (para aplicações multi-usuário).

Operações principais:

• Gerar links de autorização para fluxo OAuth
• Trocar códigos de autorização por tokens de acesso
• Renovar tokens expirados
• Gerenciar limites de taxa e permissões

Referência: Leia references/authentication.md para procedimentos detalhados de autenticação, implementação OAuth e melhores práticas de segurança.

2. Operações de Protocolo

Gerenciamento completo do ciclo de vida de protocolo, desde criação até publicação.

Operações principais:

• Pesquisar e descobrir protocolos por palavras-chave, filtros ou DOI
• Recuperar informações detalhadas de protocolo com todas as etapas
• Criar novos protocolos com metadados e tags
• Atualizar informações e configurações de protocolo
• Gerenciar etapas de protocolo (criar, atualizar, deletar, reordenar)
• Tratar materiais e reagentes de protocolo
• Publicar protocolos com emissão de DOI
• Marcar protocolos para acesso rápido
• Gerar PDFs de protocolo

Referência: Leia references/protocols_api.md para orientação abrangente sobre gerenciamento de protocolo, incluindo endpoints da API, parâmetros, workflows comuns e exemplos.

3. Discussões e Colaboração

Habilitar engajamento comunitário através de comentários e discussões.

Operações principais:

• Visualizar comentários no nível de protocolo e etapa
• Criar novos comentários e respostas encadeadas
• Editar ou deletar seus próprios comentários
• Analisar padrões de discussão e feedback
• Responder a perguntas e problemas de usuários

Referência: Leia references/discussions.md para gerenciamento de discussão, encadeamento de comentários e workflows de colaboração.

4. Gerenciamento de Espaço de Trabalho

Organizar protocolos dentro de espaços de trabalho de equipe com permissões baseadas em funções.

Operações principais:

• Listar e acessar espaços de trabalho do usuário
• Recuperar detalhes do espaço de trabalho e listas de membros
• Solicitar acesso ou ingressar em espaços de trabalho
• Listar protocolos específicos do espaço de trabalho
• Criar protocolos dentro de espaços de trabalho
• Gerenciar permissões e colaboração do espaço de trabalho

Referência: Leia references/workspaces.md para organização do espaço de trabalho, gerenciamento de permissões e padrões de colaboração em equipe.

5. Operações de Arquivo

Upload, organização e gerenciamento de arquivos associados a protocolos.

Operações principais:

• Pesquisar arquivos e pastas do espaço de trabalho
• Fazer upload de arquivos com metadados e tags
• Baixar arquivos e verificar uploads
• Organizar arquivos em hierarquias de pasta
• Atualizar metadados de arquivo
• Deletar e restaurar arquivos
• Gerenciar armazenamento e organização

Referência: Leia references/file_manager.md para procedimentos de upload de arquivo, estratégias de organização e gerenciamento de armazenamento.

6. Funcionalidades Adicionais

Funcionalidade complementar incluindo perfis, notificações e exportações.

Operações principais:

• Gerenciar perfis e configurações de usuário
• Consultar protocolos publicados recentemente
• Criar e rastrear registros de experimento
• Receber e gerenciar notificações
• Exportar dados da organização para arquivo

Referência: Leia references/additional_features.md para gerenciamento de perfil, descoberta de publicação, rastreamento de experimento e exportação de dados.

Começando

Passo 1: Configuração de Autenticação

Antes de usar qualquer funcionalidade da API protocols.io:

1. Obter um token de acesso (CLIENT_ACCESS_TOKEN ou OAUTH_ACCESS_TOKEN)
2. Ler references/authentication.md para procedimentos detalhados de autenticação
3. Armazenar o token com segurança
4. Incluir em todas as solicitações como: Authorization: Bearer YOUR_TOKEN

Passo 2: Identificar Seu Caso de Uso

Determine qual área de capacidade atende suas necessidades:

• Trabalhando com protocolos? → Leia references/protocols_api.md
• Gerenciando protocolos de equipe? → Leia references/workspaces.md
• Tratando comentários/feedback? → Leia references/discussions.md
• Fazendo upload de arquivos/dados? → Leia references/file_manager.md
• Rastreando experimentos ou perfis? → Leia references/additional_features.md

Passo 3: Implementar Integração

Siga a orientação nos arquivos de referência relevantes:

• Cada referência inclui documentação detalhada de endpoint
• Parâmetros de API e formatos de solicitação/resposta são especificados
• Casos de uso comuns e workflows são fornecidos com exemplos
• Orientação de melhores práticas e tratamento de erros incluída

URL Base e Formato de Solicitação

Todas as solicitações de API usam a URL base:

https://protocols.io/api/v3

Todas as solicitações requerem o cabeçalho Authorization:

Authorization: Bearer YOUR_ACCESS_TOKEN

A maioria dos endpoints suporta formato de solicitação/resposta JSON com Content-Type: application/json.

Opções de Formato de Conteúdo

Muitos endpoints suportam um parâmetro content_format para controlar como o conteúdo do protocolo é retornado:

• json: Formato Draft.js JSON (padrão)
• html: Formato HTML
• markdown: Formato Markdown

Incluir como parâmetro de query: ?content_format=html

Limite de Taxa

Esteja ciente dos limites de taxa da API:

• Endpoints padrão: 100 solicitações por minuto por usuário
• Endpoint de PDF: 5 solicitações/minuto (conectado), 3 solicitações/minuto (não conectado)

Implementar backoff exponencial para erros de limite de taxa (HTTP 429).

Workflows Comuns

Workflow 1: Importar e Analisar Protocolo

Para analisar um protocolo existente de protocols.io:

1. Pesquisar: Use GET /protocols com palavras-chave para encontrar protocolos relevantes
2. Recuperar: Obter detalhes completos com GET /protocols/{protocol_id}
3. Extrair: Analisar etapas, materiais e metadados para análise
4. Revisar discussões: Verificar GET /protocols/{id}/comments para feedback de usuários
5. Exportar: Gerar PDF se necessário para referência offline

Arquivos de referência: protocols_api.md, discussions.md

Workflow 2: Criar e Publicar Protocolo

Para criar um novo protocolo e publicar com DOI:

1. Autenticar: Garantir que você tenha token de acesso válido (ver authentication.md)
2. Criar: Use POST /protocols com título e descrição
3. Adicionar etapas: Para cada etapa, use POST /protocols/{id}/steps
4. Adicionar materiais: Documentar reagentes em componentes de etapa
5. Revisar: Verificar se todo conteúdo está completo e preciso
6. Publicar: Emitir DOI com POST /protocols/{id}/publish

Arquivos de referência: protocols_api.md, authentication.md

Workflow 3: Espaço de Trabalho de Laboratório Colaborativo

Para configurar gerenciamento de protocolo de equipe:

1. Criar/ingressar no espaço de trabalho: Acessar ou solicitar associação ao espaço de trabalho (ver workspaces.md)
2. Organizar estrutura: Criar hierarquia de pasta para protocolos de laboratório (ver file_manager.md)
3. Criar protocolos: Use POST /workspaces/{id}/protocols para protocolos de equipe
4. Fazer upload de arquivos: Adicionar dados experimentais e imagens
5. Habilitar discussões: Membros da equipe podem comentar e fornecer feedback
6. Rastrear experimentos: Documentar execuções de protocolo com registros de experimento

Arquivos de referência: workspaces.md, file_manager.md, protocols_api.md, discussions.md, additional_features.md

Workflow 4: Documentação de Experimento

Para rastrear execuções de protocolo e resultados:

1. Executar protocolo: Realizar protocolo em laboratório
2. Fazer upload de dados: Use File Manager API para fazer upload de resultados (ver file_manager.md)
3. Criar registro: Documentar execução com POST /protocols/{id}/runs
4. Vincular arquivos: Referenciar arquivos de dados enviados em registro de experimento
5. Anotar modificações: Documentar quaisquer desvios ou otimizações de protocolo
6. Analisar: Revisar múltiplas execuções para avaliação de reprodutibilidade

Arquivos de referência: additional_features.md, file_manager.md, protocols_api.md

Workflow 5: Descoberta e Citação de Protocolo

Para encontrar e citar protocolos em pesquisa:

1. Pesquisar: Consultar protocolos publicados com GET /publications
2. Filtrar: Usar filtros de categoria e palavra-chave para protocolos relevantes
3. Revisar: Ler detalhes de protocolo e comentários da comunidade
4. Marcar: Salvar protocolos úteis com POST /protocols/{id}/bookmarks
5. Citar: Usar DOI de protocolo em publicações (atribuição apropriada)
6. Exportar PDF: Gerar PDF formatado para referência offline

Arquivos de referência: protocols_api.md, additional_features.md

Exemplos de Solicitações Python

Pesquisa Básica de Protocolo

import requests

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

# Pesquisar protocolos 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']}")

Criar Novo Protocolo

import requests

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

# Criar protocolo
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}")

Fazer Upload de Arquivo para Espaço de Trabalho

import requests

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

# Fazer upload de arquivo
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}")

Tratamento de Erros

Implementar tratamento robusto de erros para solicitações de 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")

Arquivos de Referência

Carregue o arquivo de referência apropriado baseado em sua tarefa:

• authentication.md: Fluxos OAuth, gerenciamento de token, limite de taxa
• protocols_api.md: CRUD de protocolo, etapas, materiais, publicação, PDFs
• discussions.md: Comentários, respostas, colaboração
• workspaces.md: Espaços de trabalho de equipe, permissões, organização
• file_manager.md: Upload de arquivo, pastas, gerenciamento de armazenamento
• additional_features.md: Perfis, publicações, experimentos, notificações

Para carregar um arquivo de referência, leia o arquivo do diretório references/ quando necessário para funcionalidade específica.

Melhores Práticas

1. Autenticação: Armazenar tokens com segurança, nunca em código ou controle de versão
2. Limite de Taxa: Implementar backoff exponencial e respeitar limites de taxa
3. Tratamento de Erros: Lidar com todos os códigos de erro HTTP apropriadamente
4. Validação de Dados: Validar entrada antes de chamadas de API
5. Documentação: Documentar etapas de protocolo completamente
6. Colaboração: Usar comentários e discussões para comunicação de equipe
7. Organização: Manter convenções de nomenclatura e tagging consistentes
8. Versionamento: Rastrear versões de protocolo ao fazer atualizações
9. Atribuição: Citar protocolo apropriadamente usando DOIs
10. Backup: Exportar regularmente protocolos importantes e dados de espaço de trabalho

Recursos Adicionais

• Documentação Oficial da API: https://apidoc.protocols.io/
• Plataforma Protocols.io: https://www.protocols.io/
• Suporte: Contacte o suporte protocols.io para acesso à API e problemas técnicos
• Comunidade: Engajar com a comunidade protocols.io para melhores práticas

Solução de Problemas

Problemas de Autenticação:

• Verificar se o token é válido e não expirou
• Verificar formato do cabeçalho Authorization: Bearer YOUR_TOKEN
• Garantir tipo de token apropriado (CLIENT vs OAUTH)

Limite de Taxa:

• Implementar backoff exponencial para erros 429
• Monitorar frequência de solicitações
• Considerar cache para solicitações frequentes

Erros de Permissão:

• Verificar permissões de acesso de espaço de trabalho/protocolo
• Verificar função de usuário no espaço de trabalho
• Garantir que protocolo não seja privado se acessando sem permissão

Falhas de Upload de Arquivo:

• Verificar tamanho do arquivo contra limites do espaço de trabalho
• Verificar se tipo de arquivo é suportado
• Garantir que codificação multipart/form-data está correta

Para orientação detalhada de solução de problemas, consulte os arquivos de referência específicos cobrindo cada área de capacidade.