feat: document api contract

tests/app.rs

@@ -13,6 +13,12 @@ use std::time::Duration;
 use tower::ServiceExt;
 use wiremock::{Mock, MockServer, ResponseTemplate, matchers};
 
+const POKEAPI_MEWTWO_SPECIES: &str = include_str!("fixtures/pokeapi_mewtwo_species.json");
+const POKEAPI_PIKACHU_SPECIES: &str = include_str!("fixtures/pokeapi_pikachu_species.json");
+const FUNTRANSLATIONS_YODA_MEWTWO: &str = include_str!("fixtures/funtranslations_yoda_mewtwo.json");
+const FUNTRANSLATIONS_SHAKESPEARE_PIKACHU: &str =
+    include_str!("fixtures/funtranslations_shakespeare_pikachu.json");
+
 #[tokio::test]
 async fn health_endpoint_reports_ok() {
     let pokeapi = MockServer::start().await;
@@ -35,7 +41,7 @@ async fn health_endpoint_reports_ok() {
 async fn pokemon_endpoint_returns_basic_pokemon_information() {
     let pokeapi = MockServer::start().await;
     let translations = MockServer::start().await;
-    mount_species(&pokeapi, "mewtwo", true, "rare", "Created by science.").await;
+    mount_species_fixture(&pokeapi, "mewtwo", POKEAPI_MEWTWO_SPECIES).await;
     let app = create_app(state_for(&pokeapi, &translations));
 
     let response = app
@@ -48,7 +54,7 @@ async fn pokemon_endpoint_returns_basic_pokemon_information() {
         json_body(response).await,
         serde_json::json!({
             "name": "mewtwo",
-            "description": "Created by science.",
+            "description": "It was created by a scientist after years of horrific gene splicing and DNA engineering experiments.",
             "habitat": "rare",
             "isLegendary": true
         })
@@ -67,23 +73,26 @@ async fn pokemon_endpoint_rejects_invalid_names_before_calling_upstream() {
         .expect("request should be handled");
 
     assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+    let body = json_body(response).await;
+    assert_eq!(body["code"], "bad_request");
     assert_eq!(
-        json_body(response).await["error"],
+        body["message"],
         "pokemon name must contain only ASCII letters, digits, or hyphens"
     );
+    assert!(body["requestId"].is_string());
 }
 
 #[tokio::test]
 async fn translated_endpoint_returns_translated_description() {
     let pokeapi = MockServer::start().await;
     let translations = MockServer::start().await;
-    mount_species(&pokeapi, "pikachu", false, "forest", "Electric cheeks.").await;
+    mount_species_fixture(&pokeapi, "pikachu", POKEAPI_PIKACHU_SPECIES).await;
     Mock::given(matchers::method("POST"))
         .and(matchers::path("/translate/shakespeare"))
         .and(matchers::body_string_contains("Electric cheeks"))
-        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
-            "contents": { "translated": "Electric cheeks, prithee." }
-        })))
+        .respond_with(
+            ResponseTemplate::new(200).set_body_string(FUNTRANSLATIONS_SHAKESPEARE_PIKACHU),
+        )
         .expect(1)
         .mount(&translations)
         .await;
@@ -110,13 +119,11 @@ async fn translated_endpoint_returns_translated_description() {
 async fn translated_endpoint_uses_yoda_for_legendary_pokemon() {
     let pokeapi = MockServer::start().await;
     let translations = MockServer::start().await;
-    mount_species(&pokeapi, "mewtwo", true, "rare", "Created by science.").await;
+    mount_species_fixture(&pokeapi, "mewtwo", POKEAPI_MEWTWO_SPECIES).await;
     Mock::given(matchers::method("POST"))
         .and(matchers::path("/translate/yoda"))
-        .and(matchers::body_string_contains("Created by science"))
-        .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
-            "contents": { "translated": "Created by science, it was." }
-        })))
+        .and(matchers::body_string_contains("horrific gene splicing"))
+        .respond_with(ResponseTemplate::new(200).set_body_string(FUNTRANSLATIONS_YODA_MEWTWO))
         .expect(1)
         .mount(&translations)
         .await;
@@ -291,7 +298,10 @@ async fn rate_limit_rejects_requests_over_the_configured_burst() {
 
     assert_eq!(first.status(), StatusCode::OK);
     assert_eq!(second.status(), StatusCode::TOO_MANY_REQUESTS);
-    assert_eq!(json_body(second).await["error"], "rate limit exceeded");
+    let body = json_body(second).await;
+    assert_eq!(body["code"], "rate_limit_exceeded");
+    assert_eq!(body["message"], "rate limit exceeded");
+    assert!(body["requestId"].is_string());
 }
 
 #[tokio::test]
@@ -344,12 +354,16 @@ async fn pokemon_endpoint_maps_missing_pokemon_to_404() {
 
     let response = app
         .clone()
-        .oneshot(request("/pokemon/nope"))
+        .oneshot(request_with_request_id("/pokemon/nope", "known-request-id"))
         .await
         .expect("request should be handled");
 
     assert_eq!(response.status(), StatusCode::NOT_FOUND);
-    assert_eq!(json_body(response).await["error"], "pokemon not found");
+    assert_eq!(response.headers()["x-request-id"], "known-request-id");
+    let error = json_body(response).await;
+    assert_eq!(error["code"], "pokemon_not_found");
+    assert_eq!(error["message"], "pokemon not found");
+    assert_eq!(error["requestId"], "known-request-id");
 
     let metrics = app
         .oneshot(request("/metrics"))
@@ -377,10 +391,9 @@ async fn pokemon_endpoint_maps_pokeapi_500_to_502() {
         .expect("request should be handled");
 
     assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
-    assert_eq!(
-        json_body(response).await["error"],
-        "upstream service failed"
-    );
+    let body = json_body(response).await;
+    assert_eq!(body["code"], "upstream_unavailable");
+    assert_eq!(body["message"], "upstream service failed");
 }
 
 #[tokio::test]
@@ -400,10 +413,9 @@ async fn pokemon_endpoint_maps_invalid_pokeapi_json_to_502() {
         .expect("request should be handled");
 
     assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
-    assert_eq!(
-        json_body(response).await["error"],
-        "upstream service returned invalid data"
-    );
+    let body = json_body(response).await;
+    assert_eq!(body["code"], "upstream_invalid_data");
+    assert_eq!(body["message"], "upstream service returned invalid data");
 }
 
 #[tokio::test]
@@ -430,6 +442,14 @@ async fn translated_endpoint_does_not_call_funtranslations_when_pokeapi_fails()
     assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
 }
 
+async fn mount_species_fixture(server: &MockServer, name: &str, body: &'static str) {
+    Mock::given(matchers::method("GET"))
+        .and(matchers::path(format!("/pokemon-species/{name}")))
+        .respond_with(ResponseTemplate::new(200).set_body_string(body))
+        .mount(server)
+        .await;
+}
+
 async fn mount_species(
     server: &MockServer,
     name: &str,
@@ -472,6 +492,14 @@ fn request(path: &str) -> Request<Body> {
         .expect("request should build")
 }
 
+fn request_with_request_id(path: &str, request_id: &str) -> Request<Body> {
+    Request::builder()
+        .uri(path)
+        .header(HeaderName::from_static("x-request-id"), request_id)
+        .body(Body::empty())
+        .expect("request should build")
+}
+
 async fn json_body(response: axum::response::Response) -> Value {
     let bytes = body_bytes(response).await;
     serde_json::from_slice(&bytes).expect("body should be valid JSON")

tests/fixtures/funtranslations_shakespeare_pikachu.json

@@ -0,0 +1,8 @@
+{
+  "success": { "total": 1 },
+  "contents": {
+    "translated": "Electric cheeks, prithee.",
+    "text": "Electric cheeks.",
+    "translation": "shakespeare"
+  }
+}

tests/fixtures/funtranslations_yoda_mewtwo.json

@@ -0,0 +1,8 @@
+{
+  "success": { "total": 1 },
+  "contents": {
+    "translated": "Created by science, it was.",
+    "text": "Created by science.",
+    "translation": "yoda"
+  }
+}

tests/fixtures/pokeapi_mewtwo_species.json

@@ -0,0 +1,11 @@
+{
+  "name": "mewtwo",
+  "is_legendary": true,
+  "habitat": { "name": "rare" },
+  "flavor_text_entries": [
+    {
+      "flavor_text": "It was created by a scientist after years of horrific gene splicing and DNA engineering experiments.",
+      "language": { "name": "en" }
+    }
+  ]
+}

tests/fixtures/pokeapi_pikachu_species.json

@@ -0,0 +1,11 @@
+{
+  "name": "pikachu",
+  "is_legendary": false,
+  "habitat": { "name": "forest" },
+  "flavor_text_entries": [
+    {
+      "flavor_text": "Electric cheeks.",
+      "language": { "name": "en" }
+    }
+  ]
+}