aboutsummaryrefslogtreecommitdiffstats
path: root/rust/fatcat-api/README.md
blob: 572bcbc5992debbafea68a4f7f026f4af6339de9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# 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: 2018-06-21T18:49:41.205Z

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 AcceptEditgroup
cargo run --example client CreateContainer
cargo run --example client CreateContainerBatch
cargo run --example client CreateCreator
cargo run --example client CreateCreatorBatch
cargo run --example client CreateEditgroup
cargo run --example client CreateFile
cargo run --example client CreateFileBatch
cargo run --example client CreateRelease
cargo run --example client CreateReleaseBatch
cargo run --example client CreateWork
cargo run --example client CreateWorkBatch
cargo run --example client GetContainer
cargo run --example client GetCreator
cargo run --example client GetCreatorReleases
cargo run --example client GetEditgroup
cargo run --example client GetEditor
cargo run --example client GetEditorChangelog
cargo run --example client GetFile
cargo run --example client GetRelease
cargo run --example client GetReleaseFiles
cargo run --example client GetStats
cargo run --example client GetWork
cargo run --example client GetWorkReleases
cargo run --example client LookupContainer
cargo run --example client LookupCreator
cargo run --example client LookupFile
cargo run --example client LookupRelease
```

### 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.