path: root/rust/fatcat-api-spec/README.md

# Rust API for fatcat

A scalable, versioned, API-oriented catalog of bibliographic entities and file metadata

## 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.1.0
- Build date: 2019-01-04T00:25:33.063Z

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 CreateContainer
cargo run --example client CreateContainerBatch
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 CreateCreatorBatch
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 AuthOidc
cargo run --example client GetEditor
cargo run --example client GetEditorChangelog
cargo run --example client AcceptEditgroup
cargo run --example client CreateEditgroup
cargo run --example client GetChangelog
cargo run --example client GetChangelogEntry
cargo run --example client GetEditgroup
cargo run --example client CreateFile
cargo run --example client CreateFileBatch
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 CreateFilesetBatch
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 CreateReleaseBatch
cargo run --example client CreateWork
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 CreateWebcaptureBatch
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 CreateWorkBatch
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.1.0", 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.