Crate figshare_rs 

figshare-rs

Async Rust client for core Figshare workflows.

It provides a typed API built around FigshareClient for public article reads, exact DOI lookup, latest-version resolution, private article updates, hosted uploads, publication, and public or private file downloads, with typed models, metadata and query builders, and higher-level workflow helpers. Use FigshareClient::anonymous for public reads and FIGSHARE_TOKEN for authenticated account workflows.

The shared cross-client traits from client-uploader-traits are re-exported as figshare_rs::client_uploader_traits. Import figshare_rs::client_uploader_traits::prelude::* when you want to write generic code against the aligned client-rs trait surface.

[!WARNING] For regular free figshare.com accounts, Figshare currently offers a 20GB total storage quota and a 20GB maximum individual file size, not 20GB per document: https://help.figshare.com/article/figshare-account-limits https://info.figshare.com/user-guide/file-size-limits-and-storage/

I created this crate thinking that the 20GB limit was per document rather than total account storage. If you are looking for a general-purpose personal archival workflow, I suggest using zenodo-rs instead.

This crate still exists because Figshare is used by institutions and publishers, and the API client can still be useful in those environments.

Examples

use figshare_rs::{
    ArticleOrder, ArticleQuery, Auth, DefinedType, Endpoint, FigshareClient, OrderDirection,
};

let client = FigshareClient::builder(Auth::anonymous())
    .endpoint(Endpoint::Custom("http://localhost:8080/v2/".parse()?))
    .build()?;
let query = ArticleQuery::builder()
    .item_type(DefinedType::Dataset)
    .order(ArticleOrder::PublishedDate)
    .order_direction(OrderDirection::Desc)
    .limit(3)
    .build();

assert_eq!(client.endpoint().base_url()?.as_str(), "http://localhost:8080/v2/");
assert_eq!(query.item_type, Some(DefinedType::Dataset));
assert_eq!(query.limit, Some(3));
assert_eq!(query.order, Some(ArticleOrder::PublishedDate));

Build publication inputs locally:

use figshare_rs::{ArticleMetadata, DefinedType, UploadSource, UploadSpec};

let metadata = ArticleMetadata::builder()
    .title("Example dataset")
    .defined_type(DefinedType::Dataset)
    .description("Example upload from Rust")
    .author_named("Doe, Jane")
    .tag("example")
    .build()?;
let upload = UploadSpec::from_reader(
    "artifact.tar.gz",
    std::io::Cursor::new(vec![1_u8, 2, 3, 4]),
    4,
);

assert_eq!(metadata.title, "Example dataset");
assert_eq!(metadata.defined_type, DefinedType::Dataset);
assert_eq!(metadata.tags, vec!["example".to_owned()]);
match upload.source {
    UploadSource::Reader { content_length, .. } => assert_eq!(content_length, 4),
    UploadSource::Path(_) => unreachable!("expected reader-backed upload"),
}

Re-exports

pub use client::Auth;

pub use client::FigshareClient;

pub use client::FigshareClientBuilder;

pub use downloads::DownloadStream;

pub use downloads::ResolvedDownload;

pub use endpoint::Endpoint;

pub use error::FieldError;

pub use error::FigshareError;

pub use ids::ArticleId;

pub use ids::CategoryId;

pub use ids::Doi;

pub use ids::DoiError;

pub use ids::FileId;

pub use ids::LicenseId;

pub use metadata::ArticleMetadata;

pub use metadata::ArticleMetadataBuildError;

pub use metadata::ArticleMetadataBuilder;

pub use metadata::AuthorReference;

pub use metadata::DefinedType;

pub use model::Article;

pub use model::ArticleAuthor;

pub use model::ArticleCategory;

pub use model::ArticleEmbargo;

pub use model::ArticleFile;

pub use model::ArticleLicense;

pub use model::ArticleStatus;

pub use model::ArticleVersion;

pub use model::CustomField;

pub use model::FileStatus;

pub use model::UploadPart;

pub use model::UploadPartStatus;

pub use model::UploadSession;

pub use model::UploadStatus;

pub use poll::PollOptions;

pub use query::ArticleOrder;

pub use query::ArticleQuery;

pub use query::ArticleQueryBuilder;

pub use query::OrderDirection;

pub use upload::FileReplacePolicy;

pub use upload::UploadSource;

pub use upload::UploadSpec;

pub use workflow::PublishedArticle;

pub use client_uploader_traits;

Modules

client

Low-level typed Figshare client operations.

downloads

Streaming and file download helpers for Figshare article files.

endpoint

Endpoint selection for production or custom Figshare deployments.

error

Error types and HTTP error decoding for Figshare responses.

ids

Small identifier newtypes used throughout the public API.

metadata

Article metadata builders and defined type helpers.

model

Core data models for articles, files, licenses, uploads, and related payloads.

poll

Polling configuration for asynchronous Figshare state transitions.

query

Typed search and list query builders for Figshare articles.

upload

Upload input types and file replacement policies.

workflow

Higher-level workflow helpers built on top of the low-level client.