feat: pin the supported API contract on requests

Author: billyoshall

README.md

@@ -17,11 +17,13 @@ Get a key at [parseapi.com](https://parseapi.com). `Client::from_env()` reads `P
 
 ## API versions
 
-Choose your team's API version in [Dashboard → API version](https://parseapi.com/dashboard/versions). One setting applies to every key, including new and replacement keys. Existing teams keep `1.0.0`; new teams start on `2.0.0`. Keep the same keys and lookup URLs. Installing or upgrading the package does not change the team's setting.
+**Unreleased: planned for the next major SDK release.** This source candidate sends `Parse-Version: 2.0.0` on every request, including retries. Its response types match API `2.0.0`, and the client selects that contract automatically. No extra constructor setting or key change is needed. This behavior requires the matching API request-version release.
 
-SDK `0.3.2` targets API `1.0.0`. SDK `0.4.0` and the examples and response types in this source tree target API `2.0.0`. Use a package release documented for your team's version. These types do not model every historical response; moving to `2.0.0` may require updating code that reads renamed, moved or removed fields.
+The team setting in [Dashboard API version](https://parseapi.com/dashboard/versions) is the default for requests without a version header. This SDK's header takes precedence without changing that saved default. Existing published packages keep their documented behavior.
 
-Test the target contract in a separate development team before changing your production team's version. A change applies to every integration in that team. See [API versions and migration](https://parseapi.com/docs/versioning).
+Test the new SDK dependency in staging, then deploy the same locked dependency with your application code and existing production key. Future major SDK upgrades can deliberately select a newer API contract, so review their migration notes before upgrading. Rolling back the code and dependency restores the contract selected by that SDK release. If the older SDK does not send a version header, its requests use the team default, which must stay unchanged through that rollback window.
+
+Keep the package version locked in your dependency configuration or lockfile. The selected API contract stays fixed across releases within this planned SDK major. See [API versions and migration](https://parseapi.com/docs/versioning).
 
 ## Weather from a postal code
 

src/lib.rs

@@ -20,6 +20,8 @@ use std::fmt;
 use std::time::Duration;
 
 const DEFAULT_BASE_URL: &str = "https://api.parseapi.com";
+// The response types' wire contract. Changes require a reviewed major SDK release.
+const API_VERSION: &str = "2.0.0";
 const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
 const DEFAULT_RETRIES: u32 = 2;
 const RETRY_STATUS: [u16; 5] = [429, 500, 502, 503, 504];
@@ -1355,6 +1357,7 @@ impl Client {
 				.http
 				.get(&url)
 				.header("X-API-Key", &self.api_key)
+				.header("Parse-Version", API_VERSION)
 				.header(reqwest::header::USER_AGENT, ua.unwrap_or(USER_AGENT));
 			if !query.is_empty() {
 				request = request.query(&query);

tests/client.rs

@@ -311,6 +311,7 @@ async fn sends_key_and_user_agent() {
 	let _ = client.country("US").await;
 	let recorded = server.requests();
 	assert_eq!(recorded[0].headers["x-api-key"], "test_key_123");
+	assert_eq!(recorded[0].headers["parse-version"], "2.0.0");
 	let ua = &recorded[0].headers["user-agent"];
 	assert!(ua.starts_with("parseapi-rust/0."), "unexpected UA {ua}");
 }
@@ -324,6 +325,56 @@ async fn useragent_overrides_ua_header() {
 		server.requests()[0].headers["user-agent"],
 		"Mozilla/5.0 (Test)"
 	);
+	assert_eq!(server.requests()[0].headers["parse-version"], "2.0.0");
+	assert_eq!(server.requests()[0].headers["x-api-key"], "test_key_123");
+}
+
+#[tokio::test]
+async fn api_contract_pin_survives_retries_and_self_lookup() {
+	let server = TestServer::start_with_headers(vec![
+		(503, r#"{"code":"unavailable","message":"Try again"}"#, "Retry-After: 0\r\n".into()),
+		(200, r#"{"ip":"192.0.2.1","country":null,"deep":{"datacenter":null},"future":true}"#, String::new()),
+	]);
+	let client = Client::builder()
+		.api_key("test_key_123")
+		.base_url(&server.base_url)
+		.retries(1)
+		.build()
+		.unwrap();
+	let result = client.ip_self(IpSelfOptions::default().deep(true)).await.unwrap();
+	assert_eq!(result.ip, "192.0.2.1");
+	assert_eq!(result.country, None);
+	assert_eq!(result.deep.unwrap().datacenter, None);
+	let requests = server.requests();
+	assert_eq!(requests.len(), 2);
+	for request in requests {
+		assert_eq!(request.target, "/ip?deep=true");
+		assert_eq!(request.headers["parse-version"], "2.0.0");
+		assert_eq!(request.headers["x-api-key"], "test_key_123");
+		assert_eq!(request.headers["user-agent"], concat!("parseapi-rust/", env!("CARGO_PKG_VERSION")));
+	}
+}
+
+#[tokio::test]
+async fn api_version_errors_do_not_retry_or_fall_back() {
+	for status in [400, 410] {
+		let server = TestServer::start(vec![(status, r#"{"code":"invalid_request","message":"Unsupported API version","request_id":"req_version"}"#)]);
+		let client = Client::builder()
+			.api_key("test_key_123")
+			.base_url(&server.base_url)
+			.retries(2)
+			.build()
+			.unwrap();
+		let error = client.ip_self(None).await.unwrap_err();
+		assert_eq!(error.status(), Some(status));
+		assert_eq!(error.code(), Some("invalid_request"));
+		match error {
+			Error::Api { request_id, .. } => assert_eq!(request_id.as_deref(), Some("req_version")),
+			other => panic!("expected API error, got {other}"),
+		}
+		assert_eq!(server.requests().len(), 1);
+		assert_eq!(server.requests()[0].headers["parse-version"], "2.0.0");
+	}
 }
 
 #[test]