Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the Api Schema Contract #1801

Merged
merged 3 commits into from
Oct 11, 2017
Merged

Document the Api Schema Contract #1801

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ebfa7fb
Document the Api Schema Contract
solankisamir Oct 5, 2017
25fd037
Example for Create call and missing the pageable link
solankisamir Oct 6, 2017
6a68d06
Fix the ApiSchemaDocument object.
solankisamir Oct 6, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...nager/Microsoft.ApiManagement/2016-10-10/examples/ApiManagementServiceUpdateHostName.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@
},
"200": {
"body": {
"id": "/subscriptions/20010222-2b48-4245-a95c-090db6312d5f/resourceGroups/Admin-ResourceGroup/providers/Microsoft.ApiManagement/service/apimService1",
"id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1",
"name": "apimService1",
"type": "Microsoft.ApiManagement/service",
"tags": {
Expand Down
2 changes: 1 addition & 1 deletion ...tion/apimanagement/resource-manager/Microsoft.ApiManagement/2017-03-01/apimanagement.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -411,7 +411,7 @@
"properties": {
"policyContent": {
"type": "string",
"description": "Xml Encoded contents of the Policy."
"description": "Json escaped Xml Encoded contents of the Policy."
}
},
"required": [
Expand Down
294 changes: 294 additions & 0 deletions ...ification/apimanagement/resource-manager/Microsoft.ApiManagement/2017-03-01/apimapis.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1102,6 +1102,232 @@
}
}
}
},
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/schemas": {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is schemas a tracked or a untracked resource. If tracked PATCH would be needed. But I am guessing this is untracked resource. Please confirm

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

untracked resource

In reply to: 143310482 [](ancestors = 143310482)

"get": {
"tags": [
"ApiSchema"
],
"operationId": "ApiSchema_ListByApi",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this operation returns pageable results I believe you need to annotate it with the x-ms-pageable extension. See here for more information.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice catch. #fixed

"description": "Get the schema configuration at the API level.",
"x-ms-examples": {
"ApiManagementListApiSchemas": {
"$ref": "./examples/ApiManagementListApiSchemas.json"
}
},
"parameters": [
{
"$ref": "./apimanagement.json#/parameters/ResourceGroupNameParameter"
},
{
"$ref": "./apimanagement.json#/parameters/ServiceNameParameter"
},
{
"$ref": "#/parameters/ApiIdParameter"
},
{
"$ref": "./apimanagement.json#/parameters/ApiVersionParameter"
},
{
"$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter"
}
],
"responses": {
"200": {
"description": "Apis Schema Collection.",
"schema": {
"$ref": "#/definitions/SchemaCollection"
},
"headers": {
"ETag": {
"description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.",
"type": "string"
}
}
},
"default": {
"description": "Error response describing why the operation failed.",
"schema": {
"$ref": "./apimanagement.json#/definitions/ErrorResponse"
}
}
},
"x-ms-pageable": {
"nextLinkName": "nextLink"
}
}
},
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/schemas/{schemaId}": {
"get": {
"tags": [
"ApiSchema"
],
"operationId": "ApiSchema_Get",
"description": "Get the schema configuration at the API level.",
"x-ms-examples": {
"ApiManagementGetApiSchema": {
"$ref": "./examples/ApiManagementGetApiSchema.json"
}
},
"parameters": [
{
"$ref": "./apimanagement.json#/parameters/ResourceGroupNameParameter"
},
{
"$ref": "./apimanagement.json#/parameters/ServiceNameParameter"
},
{
"$ref": "#/parameters/ApiIdParameter"
},
{
"$ref": "#/parameters/SchemaIdParameter"
},
{
"$ref": "./apimanagement.json#/parameters/ApiVersionParameter"
},
{
"$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter"
}
],
"responses": {
"200": {
"description": "Api Schema information.",
"schema": {
"$ref": "#/definitions/SchemaContract"
},
"headers": {
"ETag": {
"description": "Current entity state version. Should be treated as opaque and used to make conditional HTTP requests.",
"type": "string"
}
}
},
"default": {
"description": "Error response describing why the operation failed.",
"schema": {
"$ref": "./apimanagement.json#/definitions/ErrorResponse"
}
}
}
},
"put": {
"tags": [
"ApiSchema"
],
"operationId": "ApiSchema_CreateOrUpdate",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Example missing for this operation.

"description": "Creates or updates schema configuration for the API.",
"x-ms-examples": {
"ApiManagementCreateApiSchema": {
"$ref": "./examples/ApiManagementCreateApiSchema.json"
}
},
"parameters": [
{
"$ref": "./apimanagement.json#/parameters/ResourceGroupNameParameter"
},
{
"$ref": "./apimanagement.json#/parameters/ServiceNameParameter"
},
{
"$ref": "#/parameters/ApiIdParameter"
},
{
"$ref": "#/parameters/SchemaIdParameter"
},
{
"name": "parameters",
"in": "body",
"schema": {
"$ref": "#/definitions/SchemaContract"
},
"required": true,
"description": "The schema contents to apply."
},
{
"name": "If-Match",
"in": "header",
"required": false,
"description": "The entity state (Etag) version of the Api Schema to update. A value of \"*\" can be used for If-Match to unconditionally apply the operation.",
"type": "string"
},
{
"$ref": "./apimanagement.json#/parameters/ApiVersionParameter"
},
{
"$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter"
}
],
"responses": {
"201": {
"description": "Api schema configuration was successfully created.",
"schema": {
"$ref": "#/definitions/SchemaContract"
}
},
"200": {
"description": "Api schema configuration of the tenant was successfully updated.",
"schema": {
"$ref": "#/definitions/SchemaContract"
}
},
"default": {
"description": "Error response describing why the operation failed.",
"schema": {
"$ref": "./apimanagement.json#/definitions/ErrorResponse"
}
}
}
},
"delete": {
"tags": [
"ApiSchema"
],
"operationId": "ApiSchema_Delete",
"description": "Deletes the schema configuration at the Api.",
"x-ms-examples": {
"ApiManagementDeleteApiSchema": {
"$ref": "./examples/ApiManagementDeleteApiSchema.json"
}
},
"parameters": [
{
"$ref": "./apimanagement.json#/parameters/ResourceGroupNameParameter"
},
{
"$ref": "./apimanagement.json#/parameters/ServiceNameParameter"
},
{
"$ref": "#/parameters/ApiIdParameter"
},
{
"$ref": "#/parameters/SchemaIdParameter"
},
{
"name": "If-Match",
"in": "header",
"required": true,
"description": "The entity state (Etag) version of the Api schema to update. A value of \"*\" can be used for If-Match to unconditionally apply the operation.",
"type": "string"
},
{
"$ref": "./apimanagement.json#/parameters/ApiVersionParameter"
},
{
"$ref": "./apimanagement.json#/parameters/SubscriptionIdParameter"
}
],
"responses": {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also add a 200 OK response.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We only return a 204 on Delete. This is an untracked resource in ARM.

In reply to: 143310351 [](ancestors = 143310351)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@solankisamir - being untracked or tracked has no bearing on this. 200 on a DELETE should be the response code returned to the customers if the resource was successfully deleted. 204OK is fine to return when the requested resource was not found but the URI was well formed. This is as per the RPC and applies to both tracked and untracked resource.

Copy link
Member Author

@solankisamir solankisamir Oct 10, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As per https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.7 if the response does not return entity then 204 is expected. We don't return entity on DELETE.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@solankisamir - Yes, I am aware of that and it is one place where ARM recommendation slightly different. But as per RPC, the recommendation is as follows -
"The resource provider can return 200 (OK) or 204 (NoContent) to indicate that the operation completed successfully. A 200 (OK) should be returned if the object exists and was deleted successfully; and a 204 (NoContent) should be used if the resource does not exist and the request is well formed."
https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/resource-api-reference.md#delete-resource
It will work and everything as you have it now, but for consistency across the azure platform, I think this should be fixed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ravbhatnagar we don't return 200 for any of our DELETE currently on this and it's parent entity and we have this behavior documented. We believe we can do this consistently across all entities with a new api-version, as it could be breaking change for some customers who have already taken dependency. What do you suggest?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@solankisamir Presumably this has been the behavior for some time, so with that in mind IMO fixing this in a new API version is the correct way to go. @ravbhatnagar are you ok with that?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I have opened a github issue tracking this #1847

"204": {
"description": "Successfully deleted the schema configuration at the API level."
},
"default": {
"description": "Error response describing why the operation failed.",
"schema": {
"$ref": "./apimanagement.json#/definitions/ErrorResponse"
}
}
}
}
}
},
"x-ms-paths": {
Expand Down Expand Up @@ -1728,6 +1954,63 @@
"header": "customHeaderParameterName"
}
}
},
"SchemaCollection": {
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/definitions/SchemaContract"
},
"description": "Api Schema Contract value."
},
"nextLink": {
"type": "string",
"description": "Next page link if any."
}
},
"description": "The response of the list schema operation."
},
"SchemaContract": {
"properties": {
"properties": {
"x-ms-client-flatten": true,
"$ref": "#/definitions/SchemaContractProperties",
"description": "Properties of the Schema."
}
},
"allOf": [
{
"$ref": "#/definitions/Resource"
}
],
"description": "Schema Contract details."
},
"SchemaContractProperties": {
"properties": {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

provisioningState property missing? DO you need it? Just wanted to check since you are returning 201. But its not long running so its not required. But still checking.

Copy link
Member Author

@solankisamir solankisamir Oct 7, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is again a proxy resource in ARM. I guess we dont need the provisioningState property.

In reply to: 143310129 [](ancestors = 143310129)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, I think we should have a call and clarify a few things around tracked and non-tracked :). If it is long running operation, and you are returning 201 for the LRO, you will need to add a provisioning state property. Is it LRO?

Copy link
Member Author

@solankisamir solankisamir Oct 10, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not a LRO.

"contentType": {
"type": "string",
"description": "Must be a valid a media type used in a Content-Type header as defined in the RFC 2616. Media type of the schema document (e.g. application/json, application/xml)."
},
"document": {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a upper limit on the size of this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no upper size limit.

In reply to: 143310265 [](ancestors = 143310265)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good.

"x-ms-client-flatten": true,
"$ref": "#/definitions/SchemaDocumentProperties",
"description": "Properties of the Schema Document."
}
},
"required": [
"contentType"
],
"description": "Schema contract Properties."
},
"SchemaDocumentProperties": {
"properties": {
"value": {
"type": "string",
"description": "Json escaped string defining the document representing the Schema."
}
},
"description": "Schema Document Properties."
}
},
"parameters": {
Expand All @@ -1752,6 +2035,17 @@
"maxLength": 256,
"pattern": "^[^*#&+:<>?]+$",
"x-ms-parameter-location": "method"
},
"SchemaIdParameter": {
"name": "schemaId",
"in": "path",
"required": true,
"type": "string",
"description": "Schema identifier within an API. Must be unique in the current API Management service instance.",
"minLength": 1,
"maxLength": 256,
"pattern": "^[^*#&+:<>?]+$",
"x-ms-parameter-location": "method"
}
}
}
Loading