path: root/rust/fatcat-openapi/README.md

# Rust API for fatcat

Fatcat is a scalable, versioned, API-oriented catalog of bibliographic entities and file metadata.  <!-- STARTLONGDESCRIPTION --> These API reference documents, along with client software libraries, are generated automatically from an OpenAPI 2.0 (\"Swagger\") definition file.  ## Introduction   A higher-level introduction to the API, as well as a description of the fatcat data model, are available in [\"The Fatcat Guide\"](https://guide.fatcat.wiki/). The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html) section demonstrating end-to-end tasks like creating entities as part of editgroups, or safely merging duplicate entities.  ### Expectations and Best Practices  A test/staging QA API instance of fatcat is available at <https://api.qa.fatcat.wiki/v0>. The database backing this instance is separate from the production interface, and is periodically rebuilt from snapshots of the full production database, meaning that edits on the QA server will *NOT* persist, and that semantics like the changelog index monotonically increasing *MAY* be broken. Developers are expexcted to test their scripts and tools against the QA instance before running against production.  Fatcat is made available as a gratis (no cost) and libre (freedom preserving) service to the public, with limited funding and resources. We welcome new and unforseen uses and contributions, but may need to impose restrictions (like rate-limits) to keep the service functional for other users, and in extreme cases reserve the option to block accounts and IP ranges if necessary to keep the service operational.  The Internet Archive owns and operates it's own server equipment and data centers, and operations are optimized for low-cost, not high-availability. Users and partners should expect some downtime on the fatcat API, on the order of hours a month.  Periodic metadata exports are available for batch processing, and database snapshots can be used to create locally-hosted mirrors of the service for more intensive and reliable querying.  ### Other Nitty Gritties  Cross-origin requests are allowed for the API service, to enable third parties to build in-browser applications.  A metadata search service is available at <https://search.fatcat.wiki> (and <https://search.qa.fatcat.wiki>). The API is currently the raw elasticsearch API, with only GET (read) requests allowed. This public service is experimental and may be removed or limited in the future.  ## Authentication  The API allows basic read-only \"GET\" HTTP requests with no authentication. Proposing changes to the metadata, or other mutating requests (\"PUT\", \"POST\", \"DELETE\") all require authentication, and some operations require additional account permissions.  End-user account creation and login happens through the web interface. From a logged-in editor profile page, you can generate a API token. Tokens are \"macaroons\", similar to JWT tokens, and are used for all API authentication. The web interface includes macaroons in browser cookies and passes them through to the API to authenticate editor actions.  <!-- ReDoc-Inject: <security-definitions> --> <!-- ENDLONGDESCRIPTION --> 

## Overview
This client/server was generated by the [swagger-codegen]
(https://github.com/swagger-api/swagger-codegen) project.
By using the [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) from a remote server, you can easily generate a server stub.
-

To see how to make this your own, look here:

[README](https://github.com/swagger-api/swagger-codegen/blob/master/README.md)

- API version: 0.3.3
- Build date: 2020-11-17T23:34:45.205Z
For more information, please visit [https://fatcat.wiki](https://fatcat.wiki)

This autogenerated project defines an API crate `fatcat` which contains:
* An `Api` trait defining the API in Rust.
* Data types representing the underlying data model.
* A `Client` type which implements `Api` and issues HTTP requests for each operation.
* A router which accepts HTTP requests and invokes the appropriate `Api` method for each operation.

It also contains an example server and client which make use of `fatcat`:
* The example server starts up a web server using the `fatcat` router,
  and supplies a trivial implementation of `Api` which returns failure for every operation.
* The example client provides a CLI which lets you invoke any single operation on the
  `fatcat` client by passing appropriate arguments on the command line.

You can use the example server and client as a basis for your own code.
See below for [more detail on implementing a server](#writing-a-server).


## Examples

Run examples with:

```
cargo run --example <example-name>
```

To pass in arguments to the examples, put them after `--`, for example:

```
cargo run --example client -- --help
```

### Running the server
To run the server, follow these simple steps:

```
cargo run --example server
```

### Running a client
To run a client, follow one of the following simple steps:

```
cargo run --example client AuthCheck
cargo run --example client AuthOidc
cargo run --example client CreateAuthToken
cargo run --example client GetChangelog
cargo run --example client GetChangelogEntry
cargo run --example client CreateContainer
cargo run --example client CreateContainerAutoBatch
cargo run --example client DeleteContainer
cargo run --example client DeleteContainerEdit
cargo run --example client GetContainer
cargo run --example client GetContainerEdit
cargo run --example client GetContainerHistory
cargo run --example client GetContainerRedirects
cargo run --example client GetContainerRevision
cargo run --example client LookupContainer
cargo run --example client UpdateContainer
cargo run --example client CreateCreator
cargo run --example client CreateCreatorAutoBatch
cargo run --example client DeleteCreator
cargo run --example client DeleteCreatorEdit
cargo run --example client GetCreator
cargo run --example client GetCreatorEdit
cargo run --example client GetCreatorHistory
cargo run --example client GetCreatorRedirects
cargo run --example client GetCreatorReleases
cargo run --example client GetCreatorRevision
cargo run --example client LookupCreator
cargo run --example client UpdateCreator
cargo run --example client AcceptEditgroup
cargo run --example client CreateEditgroup
cargo run --example client CreateEditgroupAnnotation
cargo run --example client GetEditgroup
cargo run --example client GetEditgroupAnnotations
cargo run --example client GetEditgroupsReviewable
cargo run --example client UpdateEditgroup
cargo run --example client GetEditor
cargo run --example client GetEditorAnnotations
cargo run --example client GetEditorEditgroups
cargo run --example client UpdateEditor
cargo run --example client CreateFile
cargo run --example client CreateFileAutoBatch
cargo run --example client DeleteFile
cargo run --example client DeleteFileEdit
cargo run --example client GetFile
cargo run --example client GetFileEdit
cargo run --example client GetFileHistory
cargo run --example client GetFileRedirects
cargo run --example client GetFileRevision
cargo run --example client LookupFile
cargo run --example client UpdateFile
cargo run --example client CreateFileset
cargo run --example client CreateFilesetAutoBatch
cargo run --example client DeleteFileset
cargo run --example client DeleteFilesetEdit
cargo run --example client GetFileset
cargo run --example client GetFilesetEdit
cargo run --example client GetFilesetHistory
cargo run --example client GetFilesetRedirects
cargo run --example client GetFilesetRevision
cargo run --example client UpdateFileset
cargo run --example client CreateRelease
cargo run --example client CreateReleaseAutoBatch
cargo run --example client DeleteRelease
cargo run --example client DeleteReleaseEdit
cargo run --example client GetRelease
cargo run --example client GetReleaseEdit
cargo run --example client GetReleaseFiles
cargo run --example client GetReleaseFilesets
cargo run --example client GetReleaseHistory
cargo run --example client GetReleaseRedirects
cargo run --example client GetReleaseRevision
cargo run --example client GetReleaseWebcaptures
cargo run --example client LookupRelease
cargo run --example client UpdateRelease
cargo run --example client CreateWebcapture
cargo run --example client CreateWebcaptureAutoBatch
cargo run --example client DeleteWebcapture
cargo run --example client DeleteWebcaptureEdit
cargo run --example client GetWebcapture
cargo run --example client GetWebcaptureEdit
cargo run --example client GetWebcaptureHistory
cargo run --example client GetWebcaptureRedirects
cargo run --example client GetWebcaptureRevision
cargo run --example client UpdateWebcapture
cargo run --example client CreateWork
cargo run --example client CreateWorkAutoBatch
cargo run --example client DeleteWork
cargo run --example client DeleteWorkEdit
cargo run --example client GetWork
cargo run --example client GetWorkEdit
cargo run --example client GetWorkHistory
cargo run --example client GetWorkRedirects
cargo run --example client GetWorkReleases
cargo run --example client GetWorkRevision
cargo run --example client UpdateWork
```

### HTTPS
The examples can be run in HTTPS mode by passing in the flag `--https`, for example:

```
cargo run --example server -- --https
```

This will use the keys/certificates from the examples directory. Note that the server chain is signed with
`CN=localhost`.


## Writing a server

The server example is designed to form the basis for implementing your own server. Simply follow these steps.

* Set up a new Rust project, e.g., with `cargo init --bin`.
* Insert `fatcat` into the `members` array under [workspace] in the root `Cargo.toml`, e.g., `members = [ "fatcat" ]`.
* Add `fatcat = {version = "0.3.3", path = "fatcat"}` under `[dependencies]` in the root `Cargo.toml`.
* Copy the `[dependencies]` and `[dev-dependencies]` from `fatcat/Cargo.toml` into the root `Cargo.toml`'s `[dependencies]` section.
  * Copy all of the `[dev-dependencies]`, but only the `[dependencies]` that are required by the example server. These should be clearly indicated by comments.
  * Remove `"optional = true"` from each of these lines if present.

Each autogenerated API will contain an implementation stub and main entry point, which should be copied into your project the first time:
```
cp fatcat/examples/server.rs src/main.rs
cp fatcat/examples/server_lib/mod.rs src/lib.rs
cp fatcat/examples/server_lib/server.rs src/server.rs
```

Now

* From `src/main.rs`, remove the `mod server_lib;` line, and uncomment and fill in the `extern crate` line with the name of this server crate.
* Move the block of imports "required by the service library" from `src/main.rs` to `src/lib.rs` and uncomment.
* Change the `let server = server::Server {};` line to `let server = SERVICE_NAME::server().unwrap();` where `SERVICE_NAME` is the name of the server crate.
* Run `cargo build` to check it builds.
* Run `cargo fmt` to reformat the code.
* Commit the result before making any further changes (lest format changes get confused with your own updates).

Now replace the implementations in `src/server.rs` with your own code as required.

## Updating your server to track API changes

Later, if the API changes, you can copy new sections  from the autogenerated API stub into your implementation.
Alternatively, implement the now-missing methods based on the compiler's error messages.