diff options
| -rw-r--r-- | fatcat-openapi2.yml | 10 | ||||
| -rw-r--r-- | guide/src/editing_quickstart.md | 4 | ||||
| -rw-r--r-- | guide/src/http_api.md | 4 | ||||
| -rw-r--r-- | rust/fatcat-openapi/README.md | 4 |
4 files changed, 12 insertions, 10 deletions
diff --git a/fatcat-openapi2.yml b/fatcat-openapi2.yml index ce0d8331..450e4a52 100644 --- a/fatcat-openapi2.yml +++ b/fatcat-openapi2.yml @@ -31,6 +31,8 @@ info: their scripts and tools against the QA instance before running against production. + NOTE: as of Spring 2021, the QA server is temporarily unavailable. + 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 @@ -52,10 +54,10 @@ info: 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. + A metadata search service is available at <https://search.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 diff --git a/guide/src/editing_quickstart.md b/guide/src/editing_quickstart.md index 05728d58..56fb2357 100644 --- a/guide/src/editing_quickstart.md +++ b/guide/src/editing_quickstart.md @@ -4,8 +4,8 @@ This tutorial describes how to make edits to the Fatcat catalog using the web interface. We will add a new `file` to an existing `release`, then update the release to point at a different `container`. You can follow these directions on -either the [QA](https://qa.fatcat.wiki) or [production](https://fatcat.wiki) -public catalogs. You will: +either the [QA](https://qa.fatcat.wiki) (NOTE: QA not available as of Spring +2021) or [production](https://fatcat.wiki) public catalogs. You will: - create an editor account and log-in - create a new `file` entity diff --git a/guide/src/http_api.md b/guide/src/http_api.md index e1b7f557..7c6fc2aa 100644 --- a/guide/src/http_api.md +++ b/guide/src/http_api.md @@ -7,7 +7,7 @@ A declarative specification of all API endpoints, JSON data models, and response types is available in OpenAPI 2.0 format. Code generation tools are used to generate both server-side type-safe endpoint routes and client-side libraries. Auto-generated reference documentation is, for now, available at -<https://api.qa.fatcat.wiki>. +<https://api.fatcat.wiki>. All API traffic is over HTTPS; there is no HTTP endpoint, even for read-only operations. All endpoints accept and return only JSON serialized content. @@ -67,7 +67,7 @@ metadata, it is possible to include linked entities in responses using the includes an optional `container_id` field which points to a container entity. If the `expand` parameter is set: - https://api.qa.fatcat.wiki/v0/release/aaaaaaaaaaaaarceaaaaaaaaam?expand=container + https://api.fatcat.wiki/v0/release/aaaaaaaaaaaaarceaaaaaaaaam?expand=container Then the full container model will be included under the `container` field. Multiple expand parameters can be passed, comma-separated. diff --git a/rust/fatcat-openapi/README.md b/rust/fatcat-openapi/README.md index 27137793..78d95fbf 100644 --- a/rust/fatcat-openapi/README.md +++ b/rust/fatcat-openapi/README.md @@ -1,6 +1,6 @@ # 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 --> +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. NOTE: as of Spring 2021, the QA server is temporarily unavailable. 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>. 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] @@ -13,7 +13,7 @@ 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 +- Build date: 2021-04-12T17:36:30.927Z For more information, please visit [https://fatcat.wiki](https://fatcat.wiki) This autogenerated project defines an API crate `fatcat` which contains: |