{"action":"created","issue":{"url":"https://api.github.com/repos/Azure/azure-rest-api-specs/issues/648","repository_url":"https://api.github.com/repos/Azure/azure-rest-api-specs","labels_url":"https://api.github.com/repos/Azure/azure-rest-api-specs/issues/648/labels{/name}","comments_url":"https://api.github.com/repos/Azure/azure-rest-api-specs/issues/648/comments","events_url":"https://api.github.com/repos/Azure/azure-rest-api-specs/issues/648/events","html_url":"https://github.com/Azure/azure-rest-api-specs/issues/648","id":186368713,"number":648,"title":"Proposal: x-ms-examples","user":{"login":"amarzavery","id":4521223,"avatar_url":"https://avatars.githubusercontent.com/u/4521223?v=3","gravatar_id":"","url":"https://api.github.com/users/amarzavery","html_url":"https://github.com/amarzavery","followers_url":"https://api.github.com/users/amarzavery/followers","following_url":"https://api.github.com/users/amarzavery/following{/other_user}","gists_url":"https://api.github.com/users/amarzavery/gists{/gist_id}","starred_url":"https://api.github.com/users/amarzavery/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/amarzavery/subscriptions","organizations_url":"https://api.github.com/users/amarzavery/orgs","repos_url":"https://api.github.com/users/amarzavery/repos","events_url":"https://api.github.com/users/amarzavery/events{/privacy}","received_events_url":"https://api.github.com/users/amarzavery/received_events","type":"User","site_admin":false},"labels":[{"id":374571230,"url":"https://api.github.com/repos/Azure/azure-rest-api-specs/labels/discussion","name":"discussion","color":"5319e7","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":3,"created_at":"2016-10-31T19:01:51Z","updated_at":"2016-10-31T21:37:38Z","closed_at":null,"body":"## Current mechanism and its shortcomings\r\nWe looked at the current mechanism/format provided by swagger specification to provide examples.\r\n- _**For a response**_, swagger specification says:\r\n \r\nField Pattern | Type | Description\r\n---|:---:|---\r\n{mime type} | Any | The name of the property MUST be one of the Operation `produces` values (either implicit or inherited). The value SHOULD be an example of what such a response would look like.\r\n \r\n**Illustration**:\r\n```json5\r\n{\r\n  \"application/json\": {\r\n    \"name\": \"Puma\",\r\n    \"type\": \"Dog\",\r\n    \"color\": \"Black\",\r\n    \"gender\": \"Female\",\r\n    \"breed\": \"Mixed\"\r\n  }\r\n}\r\n```\r\n \r\n**_shortcomings/concerns_**: What if the service team wants to show different examples. Scenario: GET on NetworkInterface with $expand and without $expand will have an impact on the NetworkSecurityGroup property of the NIC. In the former it will be a full blown NSG and in the latter it will be a Subresource(object with one property ‘id’)?\r\n \r\n  - _**For any model definition**_ (body parameter is a model definition; example: StorageAccountCreateParameters), swagger specfication says:\r\n \r\nField Name | Type | Description\r\n---|:---:|---\r\nexample | Any | _A free-form property to include an example of an instance for this schema._\r\n \r\n**_shortcomings/concerns_**: Well this is good. But it does not provide a holistic picture of the entire request/response. We have to do extra processing to join the dots. _When a Service developer thinks about an API endpoint, he/she would think in terms of sending a request to the endpoint and receiving a response from that endpoint._\r\n \r\n \r\n_**Hence, having an extension at every operation level in a spec, would give us the biggest bang for the buck.**_\r\n \r\n**Benefits from this extension**: \r\n- This will provide enough information about making a request against an endpoint/API.\r\n- The sample data (provided by the service developer) in the extension can be used to validate the data models (as a part of the Travis CI while the PR is sent to the azure-rest-apis-specs repo).\r\n- It can also be used to test the API/endpoint by running a live request with the help of some custom tool.\r\n  - The live request can be recorded and the recording can be saved in a json format per scenario. This recording can then be used (directly or after some processing) to run playback tests in the sdk \r\n- It forms the basis of better documentation. The doc team can leverage this in lightening up the REST API documentation.\r\n \r\n> **NOTE: We would not like to pollute the swagger spec with sample data. Hence the extension will contain a reference to the sample (a json file) in an adjacent folder of the spec.**\r\n \r\nFor example: The location of storage spec is: \r\n- azure-rest-api-specs/arm-storage/2016-01-01/swagger/storage.json. So the examples for that _**api-version**_ can reside at\r\n- azure-rest-api-specs/arm-storage/2016-01-01/examples/createStorageAccount.json\r\n \r\n_This will keep the spec cleaner and easy to manage._\r\n \r\n## Structure of the extension\r\n- **How the extension would look in the swagger spec?**\r\n```json5\r\n{\r\n  \"info\": { ... },\r\n  \"paths\": {\r\n   \"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{accountName}\": {\r\n      \"put\": {\r\n        \"operationId\": \"StorageAccounts_CreateOrUpdate\",\r\n        \"description\": \"Creates or updates a storage account.\",\r\n        \"x-ms-examples\": {\r\n          \"Create a storage account\": { \"$ref\": \"../examples/createStorageAccount.json\" },\r\n          \"Update a storage account\": { \"$ref\": \"../examples/updateStorageAccount.json\" }\r\n        },\r\n        \"parameters\": [ ... ],\r\n        \"responses\": { ... }\r\n      }\r\n    }\r\n  },\r\n  \"definitions\": { ... }\r\n}\r\n```\r\n- **Skeleton of the extension**\r\n```json5\r\n\"x-ms-examples\": {\r\n  \"example-name\": {\r\n    \"parameters\": {\r\n       \"path\": { ... },\r\n       \"query\": { ... },\r\n       \"header\": { ... },\r\n       \"body\": { ... }\r\n    },\r\n    \"responses\": {\r\n      \"statusCode1\": {\r\n        \"headers\": { ... },\r\n        \"body\": { ... }\r\n      },\r\n      \"statuscode2\": { ... }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n- **How would the content of an example file look like ?**\r\n\r\n```json5\r\n{\r\n  \"parameters\": {\r\n    \"path\": {\r\n      \"subscriptionId\": \"34adfa4f-cedf-4dc0-ba29-b6d1a69ab345\",\r\n      \"resourceGroupName\": \"testrg123\",\r\n      \"storageAccountName\": \"testacc6141\"\r\n    },\r\n    \"query\": {\r\n      \"api-version\": \"2016-01-01\"\r\n    },\r\n    \"header\": {\r\n    },\r\n    \"body\": {\r\n      \"sku\": { \r\n        \"name\": 'Standard_LRS' \r\n      },\r\n      \"kind\": 'Storage',\r\n      \"location\": 'eastasia',\r\n      \"properties\": { \r\n        \"encryption\": { \r\n          \"services\": { \r\n            \"blob\": { \r\n              \"enabled\": true \r\n            }\r\n          },\r\n          \"eySource\": 'Microsoft.Storage' \r\n        }\r\n      }\r\n    }\r\n  },\r\n  \"responses\": {\r\n    \"200\": {\r\n      \"headers\": {\r\n      },\r\n      \"body\": {\r\n        \"id\": \"/subscriptions/34adfa4f-cedf-4dc0-ba29-b6d1a69ab345/resourceGroups/testrg123/providers/Microsoft.Storage/storageAccounts/testacc6141\",\r\n        \"kind\": \"Storage\",\r\n        \"location\": \"eastasia\",\r\n        \"name\": \"testacc6141\",\r\n        \"properties\": {\r\n          \"creationTime\": \"2016-04-12T19:20:33.2288820Z\",\r\n          \"encryption\": {\r\n            \"keySource\": \"Microsoft.Storage\",\r\n            \"services\": {\r\n              \"blob\": {\r\n                \"enabled\": true,\r\n                \"lastEnabledTime\": \"2016-04-12T19:20:33.2298823Z\"\r\n              }\r\n            }\r\n          },\r\n          \"primaryEndpoints\": {\r\n            \"blob\": \"https://testacc6141.blob.core.windows.net/\",\r\n            \"file\": \"https://testacc6141.file.core.windows.net/\",\r\n            \"queue\": \"https://testacc6141.queue.core.windows.net/\",\r\n            \"table\": \"https://testacc6141.table.core.windows.net/\"\r\n          },\r\n          \"primaryLocation\": \"eastasia\",\r\n          \"provisioningState\": \"Succeeded\",\r\n          \"statusOfPrimary\": \"Available\"\r\n        },\r\n        \"sku\": {\r\n          \"name\": \"Standard_LRS\",\r\n          \"tier\": \"Standard\"\r\n        },\r\n        \"tags\": {},\r\n        \"type\": \"Microsoft.Storage/storageAccounts\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```"},"comment":{"url":"https://api.github.com/repos/Azure/azure-rest-api-specs/issues/comments/257427985","html_url":"https://github.com/Azure/azure-rest-api-specs/issues/648#issuecomment-257427985","issue_url":"https://api.github.com/repos/Azure/azure-rest-api-specs/issues/648","id":257427985,"user":{"login":"amarzavery","id":4521223,"avatar_url":"https://avatars.githubusercontent.com/u/4521223?v=3","gravatar_id":"","url":"https://api.github.com/users/amarzavery","html_url":"https://github.com/amarzavery","followers_url":"https://api.github.com/users/amarzavery/followers","following_url":"https://api.github.com/users/amarzavery/following{/other_user}","gists_url":"https://api.github.com/users/amarzavery/gists{/gist_id}","starred_url":"https://api.github.com/users/amarzavery/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/amarzavery/subscriptions","organizations_url":"https://api.github.com/users/amarzavery/orgs","repos_url":"https://api.github.com/users/amarzavery/repos","events_url":"https://api.github.com/users/amarzavery/events{/privacy}","received_events_url":"https://api.github.com/users/amarzavery/received_events","type":"User","site_admin":false},"created_at":"2016-10-31T21:37:38Z","updated_at":"2016-10-31T21:37:38Z","body":"- The example provided for response of an API in the search swagger spec is **_slightly incorrect_**. The example of a response should be associated with a mime-type, as described in the swagger specification over [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#example-object).\r\n- Network and Compute specs have the same model for input and output (body parameter of a PUT and response of the PUT operation are the same).\r\n- Spec author would want to document separate samples/examples for Operations that fall into the category of \"createOrUpdate\". A sample for Create and a sample for update, (both for input and output).\r\n**The association with mime-type is a bummer, as the author can only provide one example per mime-type.**\r\n- Adding sample data to the spec, would make the specs more lengthy (some specs are already 18000 lines long). \r\n- Benefits of the extension are already laid out in the proposal. The biggest one is it provides a snapshot of the request and the response for that API all in one place."}}
{"actor":{"display_login":"amarzavery"}}