diff options
Diffstat (limited to 'rust/fatcat-api-spec/README.md')
-rw-r--r-- | rust/fatcat-api-spec/README.md | 198 |
1 files changed, 0 insertions, 198 deletions
diff --git a/rust/fatcat-api-spec/README.md b/rust/fatcat-api-spec/README.md deleted file mode 100644 index b175a762..00000000 --- a/rust/fatcat-api-spec/README.md +++ /dev/null @@ -1,198 +0,0 @@ -# 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.3.0 -- Build date: 2019-05-21T18:36:07.221Z - -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 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 AuthCheck -cargo run --example client AuthOidc -cargo run --example client GetEditgroupsReviewable -cargo run --example client GetEditor -cargo run --example client GetEditorEditgroups -cargo run --example client UpdateEditgroup -cargo run --example client UpdateEditor -cargo run --example client AcceptEditgroup -cargo run --example client CreateEditgroup -cargo run --example client CreateEditgroupAnnotation -cargo run --example client GetChangelog -cargo run --example client GetChangelogEntry -cargo run --example client GetEditgroup -cargo run --example client GetEditgroupAnnotations -cargo run --example client GetEditorAnnotations -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 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 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 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.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. |