# REST API Client Integration

> Use when you have a batch of chemical compounds (identifiers and structures in SMILES, InChI, or IUPAC format) that need to be submitted to a remote REST API for classification or analysis, and you require the server's response (query ID and status) to track or retrieve results asynchronously.

- Skill: `holobiomicslab/rest-api-client-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/rest-api-client-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/rest-api-client-integration/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/rest-api-client-integration

---


# rest-api-client-integration

> **License: noncommercial** — confirm your use is a permitted (noncommercial) purpose before applying; commercial use requires a separate license (see `metadata.tool_license`). <!-- asb-license-banner -->
## Summary

Construct and execute HTTP POST requests to remote REST APIs using a Ruby client library, formatting compound data as tab-separated values and parsing JSON responses for downstream polling or result retrieval. This skill enables programmatic submission of chemical structure queries to web services like ClassyFire.

## When to use

You have a batch of chemical compounds (identifiers and structures in SMILES, InChI, or IUPAC format) that need to be submitted to a remote REST API for classification or analysis, and you require the server's response (query ID and status) to track or retrieve results asynchronously.

## When NOT to use

- The API endpoint does not accept POST requests or requires a different HTTP method (GET, PUT, DELETE).
- Compound structures are already encoded in a proprietary binary format or database blob incompatible with text-based SMILES/InChI/IUPAC representation.
- The REST API does not return a query ID or requires synchronous response with results embedded in the initial POST response, rather than asynchronous polling.

## Inputs

- compound_identifier (string)
- chemical_structure_representation (SMILES, InChI, or IUPAC name string)
- query_label (string)
- tab-separated compound input stream (newline-delimited)

## Outputs

- query_id (string, from JSON response)
- query_status (string, from JSON response)
- JSON response object

## How to apply

Load the rest-client gem (v1.8.0) in a Ruby environment. Format your compound inputs as tab-separated lines, where each line contains a compound identifier, a tab character, and the chemical structure representation (SMILES, InChI, or IUPAC name). Construct a POST request to the API's submit_query endpoint, embedding the formatted compound data and a descriptive query label in the request body. Execute the HTTP POST call using the rest-client library and capture the JSON response. Parse the response to extract the query ID and status fields for use in subsequent polling or result-retrieval workflows. Validate that the server responds with HTTP 200–299 status and valid JSON containing query metadata.

## Related tools

- **rest-client gem** (HTTP client library for constructing and executing POST requests to the ClassyFire API submit_query endpoint) — https://github.com/rest-client/rest-client
- **Ruby** (Runtime environment for executing rest-client commands and parsing JSON responses)
- **ClassyFire API** (Remote REST web service that accepts chemical compound submissions via POST and returns query tracking metadata) — https://bitbucket.org/wishartlab/classyfire_api

## Examples

```
require 'rest-client'; response = RestClient.post('http://classyfire.wishartlab.com/queries', {query_label: 'my_batch', compounds: "aspirin\t[O-]C(=O)c1ccccc1C(C)=O\ncaffeine\tCN1C=NC2=C1C(=O)N(C(=O)N2C)C"}, {content_type: :json}); puts response
```

## Evaluation signals

- HTTP response status code is 2xx (200–299), indicating successful POST submission.
- Returned JSON response contains required fields: query_id (non-empty string) and status (e.g., 'Submitted' or 'Done').
- The query_id is unique across multiple invocations and differs from previous submission IDs.
- Subsequent polling requests using the returned query_id successfully retrieve compound classification results from the same API.
- Tab-separated input format is correctly parsed by the API with no 'malformed request' or 'format error' messages in response.

## Limitations

- The skill requires network access to the remote API endpoint; offline or firewall-blocked environments cannot execute the POST request.
- API rate limiting or server throttling may cause POST submissions to be rejected or delayed if requests exceed service quotas.
- Compound structures must be representable in SMILES, InChI, or IUPAC name format; structures in proprietary or graphical formats require conversion preprocessing.
- The rest-client gem v1.8.0 is an older release; compatibility with modern Ruby versions (3.x+) or SSL/TLS configurations may require gem updates.

## Evidence

- [intro] rest-client gem v1.8.0 requirement: "Load the rest-client gem (v1.8.0) in a Ruby environment"
- [intro] POST method and tab-separated format specification: "The submit_query method accepts a query label and tab-separated compound inputs (identifier and structural representation) separated by newlines, formatted as individual lines where each line"
- [intro] POST request construction and execution workflow: "Construct a POST request to the ClassyFire API submit_query endpoint with a query label and tab-separated compound inputs separated by newlines as the request body. Execute the HTTP POST call and"
- [intro] Query submission via POST method: "A query can be submitted using the POST method"
- [intro] ClassyFire resource and automatic classification capability: "ClassyFire is a resource that allows you to automatically classify any chemical compound based on its structure"