@typespec/http-specs 0.1.0-alpha.0

package/specs/serialization/encoded-name/json/main.tsp

@@ -0,0 +1,45 @@
+import "@typespec/http";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+
+@doc("Projection")
+@scenarioService("/serialization/encoded-name/json")
+namespace Serialization.EncodedName.Json;
+
+@route("/property")
+namespace Property {
+  model JsonEncodedNameModel {
+    /** Pass in true */
+    @encodedName("application/json", "wireName")
+    defaultName: boolean;
+  }
+
+  @scenario
+  @scenarioDoc("""
+    Testing that you send the right JSON name on the wire.
+    Your generated SDK should generate JsonEncodedNameModel with one property `defaultName` with wire name `wireName`.
+    
+    Expected request body:
+    ```json
+    {"wireName": true}
+    ```
+    """)
+  @post
+  op send(@bodyRoot body: JsonEncodedNameModel): NoContentResponse;
+
+  @scenario
+  @scenarioDoc("""
+    Testing that you deserialize the right json name over the wire.
+    
+    Your generated SDK should generate JsonEncodedNameModel with one property `defaultName` with wire name `wireName`.
+    
+    Expected response body:
+    ```json
+    {"wireName": true}
+    ```
+    """)
+  @get
+  op get(): JsonEncodedNameModel;
+}

package/specs/serialization/encoded-name/json/mockapi.ts

@@ -0,0 +1,22 @@
+import { json, passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.Serialization_EncodedName_Json_Property_send = passOnSuccess({
+  uri: "/serialization/encoded-name/json/property",
+  method: "post",
+  request: { body: { wireName: true } },
+  response: { status: 204 },
+  kind: "MockApiDefinition",
+});
+
+Scenarios.Serialization_EncodedName_Json_Property_get = passOnSuccess({
+  uri: "/serialization/encoded-name/json/property",
+  method: "get",
+  request: {},
+  response: {
+    status: 200,
+    body: json({ wireName: true }),
+  },
+  kind: "MockApiDefinition",
+});

package/specs/server/endpoint/not-defined/main.tsp

@@ -0,0 +1,20 @@
+import "@typespec/http";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+
+/**
+ * Illustrates server doesn't define endpoint. Client should automatically add an endpoint to let user pass in.
+ */
+@route("/server/endpoint/not-defined")
+@service({
+  title: "Testserver without any endpoint",
+})
+namespace Server.Endpoint.NotDefined;
+
+@scenario
+@scenarioDoc("A simple operation in a server without defining a endpoint. Expected uri: '<endpoint you start cadl-ranch>/valid'")
+@route("/valid")
+@head
+op valid(): OkResponse;

package/specs/server/endpoint/not-defined/mockapi.ts

@@ -0,0 +1,13 @@
+import { passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.Server_Endpoint_NotDefined_valid = passOnSuccess({
+  uri: "/server/endpoint/not-defined/valid",
+  method: "head",
+  request: {},
+  response: {
+    status: 200,
+  },
+  kind: "MockApiDefinition",
+});

package/specs/server/path/multiple/main.tsp

@@ -0,0 +1,47 @@
+import "@typespec/rest";
+import "@typespec/spector";
+import "@typespec/versioning";
+
+using Http;
+using Spector;
+using TypeSpec.Versioning;
+using TypeSpec.Rest;
+
+@versioned(Versions)
+@service({
+  title: "ServerPathMultiple",
+})
+@server(
+  "{endpoint}/server/path/multiple/{apiVersion}",
+  "Test server with path parameters.",
+  {
+    @doc("Pass in http://localhost:3000 for endpoint.")
+    endpoint: url,
+
+    @doc("Pass in v1.0 for API version.")
+    apiVersion: Versions,
+  }
+)
+namespace Server.Path.Multiple;
+
+@doc("Service versions")
+enum Versions {
+  @doc("Version 1.0")
+  v1_0: "v1.0",
+}
+
+@scenario
+@scenarioDoc("""
+  Operation with client path parameters.
+  
+  Expected path parameter: apiVersion=v1.0
+  """)
+op noOperationParams(): NoContentResponse;
+
+@scenario
+@scenarioDoc("""
+  Operation with client and method path parameters.
+  
+  Expected path parameter: apiVersion=v1.0, keyword=test
+  """)
+op withOperationPathParam(@path keyword: string): NoContentResponse;

package/specs/server/path/multiple/mockapi.ts

@@ -0,0 +1,23 @@
+import { passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.Server_Path_Multiple_noOperationParams = passOnSuccess({
+  uri: "/server/path/multiple/v1.0",
+  method: "get",
+  request: {},
+  response: {
+    status: 204,
+  },
+  kind: "MockApiDefinition",
+});
+
+Scenarios.Server_Path_Multiple_withOperationPathParam = passOnSuccess({
+  uri: "/server/path/multiple/v1.0/test",
+  method: "get",
+  request: {},
+  response: {
+    status: 204,
+  },
+  kind: "MockApiDefinition",
+});

package/specs/server/path/single/main.tsp

@@ -0,0 +1,24 @@
+import "@typespec/http";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+
+@doc("Illustrates server with a single path parameter @server")
+@service
+@server(
+  "{endpoint}",
+  "Testserver endpoint",
+  {
+    @doc("Need to be set as 'http://localhost:3000' in client.")
+    endpoint: url,
+  }
+)
+@route("/server/path/single")
+namespace Server.Path.Single;
+
+@scenario
+@scenarioDoc("An simple operation in a parameterized server.")
+@route("/myOp")
+@head
+op myOp(): OkResponse;

package/specs/server/path/single/mockapi.ts

@@ -0,0 +1,13 @@
+import { passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.Server_Path_Single_myOp = passOnSuccess({
+  uri: "/server/path/single/myOp",
+  method: "head",
+  request: {},
+  response: {
+    status: 200,
+  },
+  kind: "MockApiDefinition",
+});

package/specs/server/versions/not-versioned/main.tsp

@@ -0,0 +1,40 @@
+import "@typespec/http";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+
+/**
+ * Illustrates not-versioned server.
+ */
+@service
+@server(
+  "{endpoint}",
+  "Testserver endpoint",
+  {
+    /**
+     * Need to be set as 'http://localhost:3000' in client.
+     */
+    endpoint: url,
+  }
+)
+@route("/server/versions/not-versioned")
+namespace Server.Versions.NotVersioned;
+
+@scenario
+@scenarioDoc("A simple operation without api-version. Expected url: '/without-api-version', it should not contain any api-version.")
+@route("/without-api-version")
+@head
+op withoutApiVersion(): OkResponse;
+
+@scenario
+@scenarioDoc("A simple operation with query api-version, which doesn't have any default value. Expected url: '/with-query-api-version?api-version=v1.0'.")
+@route("/with-query-api-version")
+@head
+op withQueryApiVersion(@query("api-version") apiVersion: string): OkResponse;
+
+@scenario
+@scenarioDoc("A simple operation with path api-version, which doesn't have any default value. Expected url: '/with-path-api-version/v1.0'.")
+@route("/with-path-api-version")
+@head
+op withPathApiVersion(@path apiVersion: string): OkResponse;

package/specs/server/versions/not-versioned/mockapi.ts

@@ -0,0 +1,51 @@
+import { MockRequest, passOnSuccess, ScenarioMockApi, ValidationError } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+function createServerTests(uri: string, requestData?: any) {
+  let requestObject: any;
+  if (requestData) {
+    requestObject = requestData;
+  } else {
+    requestObject = {};
+  }
+  return passOnSuccess({
+    uri,
+    method: "head",
+    request: requestObject,
+    response: {
+      status: 200,
+    },
+    handler: (req: MockRequest) => {
+      if (Object.keys(req.query).length > 0) {
+        throw new ValidationError(
+          "Expected no query parameters including api-version",
+          "No query parameters",
+          req.query,
+        );
+      }
+      return { status: 200 };
+    },
+    kind: "MockApiDefinition",
+  });
+}
+
+Scenarios.Server_Versions_NotVersioned_withoutApiVersion = createServerTests(
+  "/server/versions/not-versioned/without-api-version",
+);
+Scenarios.Server_Versions_NotVersioned_withPathApiVersion = createServerTests(
+  "/server/versions/not-versioned/with-path-api-version/v1.0",
+);
+Scenarios.Server_Versions_NotVersioned_withQueryApiVersion = passOnSuccess({
+  uri: "/server/versions/not-versioned/with-query-api-version",
+  method: "head",
+  request: {
+    params: {
+      "api-version": "v1.0",
+    },
+  },
+  response: {
+    status: 200,
+  },
+  kind: "MockApiDefinition",
+});

package/specs/server/versions/versioned/main.tsp

@@ -0,0 +1,64 @@
+import "@typespec/http";
+import "@typespec/spector";
+import "@typespec/versioning";
+
+using Http;
+using Spector;
+using TypeSpec.Versioning;
+
+/**
+ * Illustrates versioned server.
+ */
+@service
+@versioned(Versions)
+@server(
+  "{endpoint}",
+  "Testserver endpoint",
+  {
+    /**
+     * Need to be set as 'http://localhost:3000' in client.
+     */
+    endpoint: url,
+  }
+)
+@route("/server/versions/versioned")
+namespace Server.Versions.Versioned;
+
+/**
+ * The version of the API.
+ */
+enum Versions {
+  /**
+   * The version 2022-12-01-preview.
+   */
+  v2021_01_01_preview: "2021-01-01-preview",
+
+  /**
+   * The version 2022-12-01-preview.
+   */
+  v2022_12_01_preview: "2022-12-01-preview",
+}
+
+@scenario
+@scenarioDoc("A simple operation without api-version. Expected url: '/without-api-version', it should not contain any api-version.")
+@route("/without-api-version")
+@head
+op withoutApiVersion(): OkResponse;
+
+@scenario
+@scenarioDoc("A simple operation with query api-version, whose default value is defined as '2022-12-01-preview'. Expected url: '/with-query-api-version?api-version=2022-12-01-preview'.")
+@route("/with-query-api-version")
+@head
+op withQueryApiVersion(@query("api-version") apiVersion: string): OkResponse;
+
+@scenario
+@scenarioDoc("A simple operation with path api-version, whose default value is defined as '2022-12-01-preview'. Expected url: '/with-path-api-version/2022-12-01-preview'.")
+@route("/with-path-api-version")
+@head
+op withPathApiVersion(@path apiVersion: string): OkResponse;
+
+@scenario
+@scenarioDoc("A simple operation with query api-version, that do NOT use the default but '2021-01-01-preview'. It's expected to be set at the client level. Expected url: '/with-old-query-api-version?api-version=2021-01-01-preview'.")
+@route("/with-query-old-api-version")
+@head
+op withQueryOldApiVersion(@query("api-version") apiVersion: string): OkResponse;

package/specs/server/versions/versioned/mockapi.ts

@@ -0,0 +1,64 @@
+import { MockRequest, passOnSuccess, ScenarioMockApi, ValidationError } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+function createServerTests(uri: string) {
+  return passOnSuccess({
+    uri,
+    method: "head",
+    request: {},
+    response: {
+      status: 200,
+    },
+    handler: (req: MockRequest) => {
+      if (Object.keys(req.query).length > 0) {
+        throw new ValidationError(
+          "Expected no query parameters including api-version",
+          "No query parameters",
+          req.query,
+        );
+      }
+      return { status: 200 };
+    },
+    kind: "MockApiDefinition",
+  });
+}
+
+Scenarios.Server_Versions_Versioned_withoutApiVersion = createServerTests(
+  "/server/versions/versioned/without-api-version",
+);
+Scenarios.Server_Versions_Versioned_withPathApiVersion = createServerTests(
+  "/server/versions/versioned/with-path-api-version/2022-12-01-preview",
+);
+
+function createAPIVersionTests(uri: string, requestData: any, serverData: string) {
+  return passOnSuccess({
+    uri,
+    method: "head",
+    request: requestData,
+    response: {
+      status: 200,
+    },
+    kind: "MockApiDefinition",
+  });
+}
+
+Scenarios.Server_Versions_Versioned_withQueryOldApiVersion = createAPIVersionTests(
+  "/server/versions/versioned/with-query-old-api-version",
+  {
+    params: {
+      "api-version": "2021-01-01-preview",
+    },
+  },
+  "2021-01-01-preview",
+);
+
+Scenarios.Server_Versions_Versioned_withQueryApiVersion = createAPIVersionTests(
+  "/server/versions/versioned/with-query-api-version",
+  {
+    params: {
+      "api-version": "2022-12-01-preview",
+    },
+  },
+  "2022-12-01-preview",
+);

package/specs/special-headers/conditional-request/main.tsp

@@ -0,0 +1,89 @@
+import "@typespec/http";
+import "@typespec/versioning";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+using TypeSpec.Versioning;
+
+@doc("Illustrates conditional request headers")
+@scenarioService("/special-headers/conditional-request")
+namespace SpecialHeaders.ConditionalRequest;
+
+@scenario
+@doc("""
+  Check when only If-Match in header is defined.
+  """)
+@scenarioDoc("""
+  Check when only If-Match in header is defined.
+  Expected header parameters:
+  - if-match="valid"
+  """)
+@post
+@route("/if-match")
+op postIfMatch(
+  @header("If-Match")
+  @doc("The request should only proceed if an entity matches this string.")
+  ifMatch?: string,
+): NoContentResponse;
+
+@scenario
+@doc("""
+  Check when only If-None-Match in header is defined.
+  """)
+@scenarioDoc("""
+  Check when only If-None-Match in header is defined.
+  Expected header parameters:
+  - if-nonematch="invalid"
+  """)
+@post
+@route("/if-none-match")
+op postIfNoneMatch(
+  @header("If-None-Match")
+  @doc("The request should only proceed if no entity matches this string.")
+  ifNoneMatch?: string,
+): NoContentResponse;
+
+@scenario
+@doc("""
+  Check when only If-Modified-Since in header is defined.
+  """)
+@scenarioDoc("""
+  Check when only If-Modified-Since in header is defined.
+  Expected header parameters:
+  - if-modified-since=Fri, 26 Aug 2022 14:38:00 GMT
+  """)
+@head
+@route("/if-modified-since")
+op headIfModifiedSince(
+  @doc("""
+    A timestamp indicating the last modified time of the resource known to the
+    client. The operation will be performed only if the resource on the service has
+    been modified since the specified time.
+    """)
+  @header("If-Modified-Since")
+  @encode(DateTimeKnownEncoding.rfc7231)
+  ifModifiedSince?: utcDateTime,
+): NoContentResponse;
+
+@scenario
+@doc("""
+  Check when only If-Unmodified-Since in header is defined.
+  """)
+@scenarioDoc("""
+  Check when only If-Unmodified-Since in header is defined.
+  Expected header parameters:
+  - if-unmodified-since=Fri, 26 Aug 2022 14:38:00 GMT
+  """)
+@post
+@route("/if-unmodified-since")
+op postIfUnmodifiedSince(
+  @doc("""
+    A timestamp indicating the last modified time of the resource known to the
+    client. The operation will be performed only if the resource on the service has
+    not been modified since the specified time.
+    """)
+  @header("If-Unmodified-Since")
+  @encode(DateTimeKnownEncoding.rfc7231)
+  ifUnmodifiedSince?: utcDateTime,
+): NoContentResponse;

package/specs/special-headers/conditional-request/mockapi.ts

@@ -0,0 +1,59 @@
+import { passOnSuccess, ScenarioMockApi } from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.SpecialHeaders_ConditionalRequest_postIfUnmodifiedSince = passOnSuccess({
+  uri: "/special-headers/conditional-request/if-unmodified-since",
+  method: "post",
+  request: {
+    headers: {
+      "if-unmodified-since": "Fri, 26 Aug 2022 14:38:00 GMT",
+    },
+  },
+  response: {
+    status: 204,
+  },
+  kind: "MockApiDefinition",
+});
+
+Scenarios.SpecialHeaders_ConditionalRequest_headIfModifiedSince = passOnSuccess({
+  uri: "/special-headers/conditional-request/if-modified-since",
+  method: "head",
+  request: {
+    headers: {
+      "if-modified-since": "Fri, 26 Aug 2022 14:38:00 GMT",
+    },
+  },
+  response: {
+    status: 204,
+  },
+  kind: "MockApiDefinition",
+});
+
+Scenarios.SpecialHeaders_ConditionalRequest_postIfMatch = passOnSuccess({
+  uri: "/special-headers/conditional-request/if-match",
+  method: "post",
+  request: {
+    headers: {
+      "if-match": '"valid"',
+    },
+  },
+  response: {
+    status: 204,
+  },
+  kind: "MockApiDefinition",
+});
+
+Scenarios.SpecialHeaders_ConditionalRequest_postIfNoneMatch = passOnSuccess({
+  uri: "/special-headers/conditional-request/if-none-match",
+  method: "post",
+  request: {
+    headers: {
+      "if-none-match": '"invalid"',
+    },
+  },
+  response: {
+    status: 204,
+  },
+  kind: "MockApiDefinition",
+});

package/specs/special-headers/repeatability/main.tsp

@@ -0,0 +1,39 @@
+import "@typespec/http";
+import "@typespec/versioning";
+import "@typespec/spector";
+
+using Http;
+using Spector;
+using TypeSpec.Versioning;
+
+@doc("Illustrates OASIS repeatability headers")
+@scenarioService("/special-headers/repeatability")
+namespace SpecialHeaders.Repeatability;
+
+model RepeatableResponse {
+  @doc("The status code.")
+  @statusCode
+  statusCode: 204;
+
+  @visibility("read")
+  @header("Repeatability-Result")
+  @doc("Indicates whether the repeatable request was accepted or rejected.")
+  repeatabilityResult?: "accepted" | "rejected";
+}
+
+@scenario
+@scenarioDoc("""
+  Check we recognize Repeatability-Request-ID and Repeatability-First-Sent.
+  """)
+@doc("""
+  Check we recognize Repeatability-Request-ID and Repeatability-First-Sent.
+  """)
+@post
+@route("/immediateSuccess")
+op immediateSuccess(
+  @header("Repeatability-Request-ID")
+  repeatabilityRequestID: string,
+
+  @header("Repeatability-First-Sent")
+  repeatabilityFirstSent: utcDateTime,
+): RepeatableResponse;

package/specs/special-headers/repeatability/mockapi.ts

@@ -0,0 +1,47 @@
+import {
+  MockRequest,
+  passOnSuccess,
+  ScenarioMockApi,
+  validateValueFormat,
+  ValidationError,
+} from "@typespec/spec-api";
+
+export const Scenarios: Record<string, ScenarioMockApi> = {};
+
+Scenarios.SpecialHeaders_Repeatability_immediateSuccess = passOnSuccess({
+  uri: "/special-headers/repeatability/immediateSuccess",
+  method: "post",
+  request: {
+    headers: {
+      "Repeatability-First-Sent": "Tue, 15 Nov 2022 12:45:26 GMT",
+      "Repeatability-Request-ID": "2378d9bc-1726-11ee-be56-0242ac120002", // fake uuid
+    },
+  },
+  response: {
+    status: 204,
+    headers: {
+      "repeatability-result": "accepted",
+    },
+  },
+  handler: (req: MockRequest) => {
+    if (!("repeatability-request-id" in req.headers)) {
+      throw new ValidationError("Repeatability-Request-ID is missing", "A UUID string", undefined);
+    }
+    if (!("repeatability-first-sent" in req.headers)) {
+      throw new ValidationError(
+        "Repeatability-First-Sent is missing",
+        "A date-time in headers format",
+        undefined,
+      );
+    }
+    validateValueFormat(req.headers["repeatability-request-id"], "uuid");
+    validateValueFormat(req.headers["repeatability-first-sent"], "rfc7231");
+    return {
+      status: 204,
+      headers: {
+        "repeatability-result": "accepted",
+      },
+    };
+  },
+  kind: "MockApiDefinition",
+});