ESC REST Northbound API Documentation

3y ago
63 Views
2 Downloads
749.55 KB
73 Pages
Last View : 18d ago
Last Download : 6m ago
Upload by : Sutton Moon
Transcription

ESC REST Northbound API DocumentationTable of ContentsResources managed by ESC RESTBehavior of ESC REST operationsESC REST API Headers/Path/Body ParametersCallbacksMedia TypeInternal IDsBodyString Restrictions in Body/Internal IDsREST API SecurityREST AuthenticationREST Https SupportREST API ListResources managed by ESC oymentsBehavior of ESC REST operationsGET operations are synchronous the request/response parameters are described with an example of arequest/responsePOST, DELETE, and PUT operations are asynchronous. The asynchronous design use the “web hooks”approach using two independent "one-way" invocations - one to start a long-running operation (Client to ESC)and the other one to notify a requester that it is completed (ESC to client)ESC REST API Headers/Path/Body ParametersCallbacks

One of the header parameters of the operation request will contain a callback field, whose value is a URI wherethe client expects a callback. If this field is not present, no callback will be performed.When the operation has completed (either successfully or unsuccessfully), ESC will perform a POST request tothe callback URI, with an entity body containing the resource for this operation. The status will be returned inthe HTTP header called esc-status-code and the status message will be returned in the HTTP header calledesc-status-message.ESC Clients can match a completion report back to the original request by comparing the value of the HTTPheader called esc-transaction-id to the one returned in the initial status response.ESC Clients are expected to provide a REST implementation for all the callbacks.Media TypeAll POST, DELETE, and PUT operations that require request and/or response body must provide a headerparameter for media type. Note, that ESC is currently tested to accept and return XML.Internal IDsIn some of the ESC REST API, there is a path parameter called "* internal id" where the asterisk is replacedby the resource type. ESC Clients must provide an internal id for its resource it wants to create. The internal idsare enforced so the ESC Clients are able to refer to them in future operations such as GET, PUT, or DELETErequests.It is recommended that the ESC Client generated internal ids within the scope of the ESC.NOTE: Reusing (recycling) of internal ids is not recommended. This practice can lead to confusion in troubleshooting.BodyIn some of the POST, PUT, and DELETE requests you are required to provide a JSON/XML body. Dependingon the resource, you will need to provide certain fields in the body to successfully execute a request. Check thebody section for each API (bottom of page) to see what fields are supported.String Restrictions in Body/Internal IDsBodySome string parameters/fields, such as id, name, are restricted by the underlying cloud provider, such asOpenstack. The allowable range for these parameters is included in the Create section for each resource, inthis notation: String minimum-length . . maximum length, for example, for Tenant name: String 1 . . 64Generally, names are either 1.64 (for Tenant/User) or 1.255 (for Network/Subnet/Flavor/Image/VM).Internal IDIds are restricted to 72 characters such as internal id 1.72 and external id 1.72.Internal id naming must conform the standards stated in RFC 3986 Uniform Resource Identifier (URI): GenericSyntax. See sections related to URI encoding, sections 2.2 Reserved Characters and 2.3 UnreservedCharacters. ESC will accept an internal id specified in the request URL form the unreserved character set:unreserved ALPHA / DIGIT / "-" / "." / " ”

NOTE: the tilde “ ” is not supported in the internal id character set.The internal id received in a request must be unique within the scope of all the domain resources (tenant,network, subnet, service catalog, deployment ) For example, you cannot create 2 networks with the sameinternal network id, even if the networks are created under different tenants.REST API SecurityREST AuthenticationOverviewESC REST API uses http basic access authentication where the ESC client will have to provide a usernameand password when making ESC REST requests. The user name and password will be encoded with Base64in transit, but not encrypted or hashed. HTTPS will be used in conjunction with Basic Authentication to providethe encryption.SetupBy default, the REST authentication is disabled. To enable it the pass the argument --enable-auth to ESCbootvm.py, ESC installation script.Username and PasswordThe REST interface has only one default username/password (admin/cisco123).The REST password can be updated using escadm tool from the ESC VM CLI: escadm rest set --username admin --password test123The REST password can be reset using escadm tool from the ESC VM CLI: escadm rest setYou can also update the password through the REST API:http://[ESCVM userName yourUsername&password yourPasswordSending an Authorized RequestTo send an authorized request an ESC client should send the request with the following header:Authorization: Basic YWRtaW46Y2lzY28xMjM where YWRtaW46Y2lzY28xMjM is the Base64 enconded string of the default username/password(admin:cisco123)Most libraries and web clients have an interface for simply providing the username/password and the app willencode the username/password and add the HTTP Basic Auth header.Example using the default admin/cisco123 credentials:

http://[ESCVM eapplication/xmlAuthorizationBasic YWRtaW46Y2lzY28xMjM REST Https SupportOverviewESC supports https communication over port 8443. ESC will generate a self-signed certificate that the client willneed to trust to get the https communication going.SetupBy default, the REST https is disabled and restricted to localhost. To enable it pass the argument --enable-httpsrest to ESC bootvm.py, ESC installation script.HA ConsiderationsIn an HA setup every ESC HA VM will have its own self-signed generated certificate. Upon an HA switchover,ESC north bound client will be required to re-accept the new certificate it will be served.REST API List01-Tenants : Manage ESC tenants/v0/tenantsGETGet all tenantsImplementation NotesAll tenants in ESC will be returned as a ListResponse Class (Status 200)Model Model Schema[{"internal tenant id": "string","external tenant id": "string","name": "string","enabled": false,"vim mapping": false,"event type": "CREATE TENANT","managed resource": false}]Response Content Typeapplication/xml

T it t!DELETE/v0/tenants/{internal tenant id}Delete a tenant from ESCImplementation NotesDelete a tenant from nal tenant id(required)DescriptionParameterTypeData TypeCallback URL forESC notificationsheaderstringInternal tenant ID(max length 72characters)pathstringResponse MessagesHTTP StatusCodeReason200Tenant deletion requestaccepted400Invalid Request404Invalid Tenant IdResponse ModelHeadersTry it out!GET/v0/tenants/{internal tenant id}Get a tenant by its nameImplementation NotesOnly tenants created using ESC will be checkedParametersParameterValueinternal tenant id(required)DescriptionParameterTypeData TypeInternal tenant ID(max length 72characters)pathstringResponse MessagesHTTP StatusCodeReason200Get request acceptedResponse ModelHeaders

HTTP StatusCodeReason404Invalid Request - Invalid TenantIDResponse ModelHeadersTry it out!/v0/tenants/{internal tenant id}POSTCreate a tenant in ESCImplementation NotesCreates a tenant which will be managed by ESC and can be used for creating other resources under it.Examplerequest:POST /v0/tenants/tentest HTTP/1.1Content-Type: application/xmlAccept: application/xmlCallback: http://127.0.0.1:9010/Body: tenant xmlns "urn:ietf:params:xml:ns:netconf:base:1.0" name example-tenant /name managed resource true /managed resource /tenant After the tenant creation operation is done, ECS will send a callback to the client with the result. Examplecallback:HTTP/1.1 201 OKContent-Type: application/xml; charset UTF-8ESC TRANSACTION ID: e: 200ESC-Status-Message: Tenant successfully created tenant xmlns "urn:ietf:params:xml:ns:netconf:base:1.0" enabled true /enabled event type CREATE TENANT /event type external tenant id 484c620285ea4f588227ff3396215980 /external tenant id internal tenant id tentest /internal tenant id name example-tenant /name managed resource true /managed resource /tenant ta Type

peData TypeTenantconfigurationpayloadbodyModel Model Schema{"internal tenant id": "string","external tenant id": "string","name": "string","enabled": false,Parameter contenttype:"vim mapping": false,application/xml"event type": "CREATE TENANT","managed resource": false}Click to set as parameter valueCallback(required)internal tenant id(required)Callback URLfor ESCnotificationsheaderInternal tenant pathID (max length72 characters)stringstringResponse MessagesHTTP StatusCodeReason200Tenant creation requestaccepted400Invalid Request409Conflicting RequestResponse ModelHeadersTry it out!02-Networks : Manage ESC networksGET/v0/{internalTenantId}/networksGet all networks under a tenantImplementation NotesAll networks under that tenant in ESC will be returned as a red)DescriptionParameterTypeData TypeInternal tenant ID ofthe network (maxlength 72 characters)pathstring

Response MessagesHTTP StatusCodeReason200Request acceptedResponse ModelHeadersTry it lNetworkId}Delete a network from an existing tenant in ESCImplementation NotesDelete a network from scriptionParameterTypeData TypeCallback URL forESC notificationsheaderstringInternal network ID(max length 72characters)pathstringInternal tenant ID ofthe network (maxlength 72 characters)pathstringResponse MessagesHTTP StatusCodeReason200Request accepted400Invalid request500Internal server errorResponse ModelHeadersTry it tworkId}Get a network by its tenant and internal network IDImplementation NotesOnly networks created using ESC will be rTypeData Type

tworkId(required)DescriptionParameterTypeData TypeInternal tenant ID ofthe network (maxlength 72characters)pathstringInternal network ID(max length 72characters)pathstringResponse MessagesHTTP StatusCodeReason200Request accepted404Network Id not foundResponse ModelHeadersTry it etworkId}Create a network under an existing tenant in ESCImplementation NotesCreate a network in scriptionParameter Data TypeTypeCallbackURL for ESCnotificationsheaderstringInternaltenant ID ofthe network(max length72characters)pathstringInternalnetwork ID(max length72characters)pathstring

ParameterValue(required)bodyDescriptionParameter Data TypeTypebodyNetworkconfigurationpayloadModel Model Schema{"internalDeploymentId": "string","internal tenant id": "string","internal network id": "string","name": "string",Parameter contenttype:"shared": false,application/xml"external tenant id": "string","tenant name": "string","external network id": "string","subnet": ["string"],"admin state up": false,"locators": {"datacenter": "string","switch name": "string"},"event type": "CREATE NETWORK","provider segmentation id": "string","router external": false,"provider physical network": "string","provider network type": "string","vlan id": 0,"switch name": "string","number of ports": 0}Click to set as parameter valueResponse MessagesHTTP StatusCodeReason200Request accepted400Invalid request404Network Id not found409Conflicting request503Unable to query VIMResponse ModelHeadersTry it out!03-Subnets : Manage ESC tion NotesAll subnet under that network in ESC will be returned as a ListGet all subnets under a network

)internalTenantIdDescriptionParameterTypeData TypeInternal network ID ofthe subnet (maxlength 72 characters)headerstringInternal tenant ID ofthe subnet (maxlength 72characters)pathstringResponse MessagesHTTP StatusCodeReason200Request accepted404Not foundResponse ModelHeadersTry it SubnetId}Delete a subnet from an existing tenant in ESCImplementation NotesDelete a subnet from criptionParameterTypeData TypeCallback URL for ESCnotificationsheaderstringInternal tenant ID ofthe subnet (maxlength 72 characters)pathstringInternal subnet ID(max length 72characters)pathstringResponse MessagesHTTP StatusCodeReason200Request accepted400Invalid RequestResponse ModelHeaders

HTTP StatusCodeReason404Not found500Internal server errorResponse ModelHeadersTry it netId}Get a subnet by its tenant and internal subnet IDImplementation NotesOnly subnets created using ESC will be terTypeData TypeInternal tenant ID ofthe subnet (maxlength 72 characters)pathstringInternal subnet ID(max length 72characters)pathstringResponse MessagesHTTP StatusCodeReason200Request accepted404Not foundResponse ModelHeadersTry it bnetId}Create a subnet under an existing tenant in ESCImplementation NotesCreate a subnet in iptionParameterTypeData TypeCallback URLfor ESCnotificati

The asynchronous design use the “web hooks” approach using two independent "one-way" invocations - one to start a long-running operation (Client to ESC) and the other one to notify a requester that it is completed (ESC to client) ESC REST API Headers/Path/Body Parameters Callbacks. One of the header parameters of the operation request will contain a callback field, whose value is a URI .

Related Documents:

REST API Security REST Authentication Overview ESC REST API uses http basic access authentication where the ESC client will have to provide a username and password when making ESC REST requests. The user name and password will be encoded with Base64 in transit, but not encrypted or hashed. HTTPS will be used in

About This Manual 1-2 Print Area Calculation 1-3 PROGRAMMING CONCEPTS Programming Language 2-2 Selecting Protocol Codes 2-3 Using Basic 2-4 Print Position Commands 2-6 COMMAND CODE QUICK REFERENCE A: ESC A Start Label 3-2 ESC A Cut, Label 3-2 ESC a Cut, Job3-2 ESC B Cut, Last 3-2 ESC AO Auto Online 3-2 ESC A1 Media Size 3-2 ESC & Form .

Printer control ESC @ 1B 40 Initialize Graphics commands ESC * 1B 2A Select bit image ESC K 1B 4B 8-dot single-density bit image ESC L 1B 4C 8-dot double-density bit image ESC Y 1B 59 8-dot double-speed double-density bit image ESC Z 1B 5A 8-dot quadruple-density bit image Kanji commands FS Y 1C 59 Specify kanji size

Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x 13 Using the REST API Plug-in Increase max-port via REST. Cisco Nexus 1000V for VMware vSphere REST API Plug-in Configuration Guide, Release 5.x 14 Using the REST API Plug-in Feature History for Using the REST API Plug-in.

Service manual Electric and Gas Combi 2008/07/28 SEV/KA Model Serial-No. / date from thru Electric: ESC 615 07020594 ESC 620 07020594 ESC 115 07020594 ESC 120 07020594 ESC 215 07020594 ESC 220 07020594 Gas: GSC 615 07020594 GSC 620 07020594 GSC 115 07020594 GSC 120 07020594 GSC 215 07020594 GSC 220 07020594 From software 3.00 1. SmartCombi Service Preposition The documentation may address .

REST API documentation process with executable API usage examples. The technique involves the interception of example REST API calls using an HTTP proxy server to auto-generate an ac-curate and updated REST API documentation. I present an industrial evaluation of the proposed technique based on a period of eighteen months of production use.

api 20 e rapid 20e api 20 ne api campy api nh api staph api 20 strep api coryne api listeriaapi 20 c aux api 20 a rapid id 32 a api 50 ch api 50 chb/e 50 chl reagents to be ordered. strips ref microorganisms suspension inoculum transfer medium i

Cambridge University Press. Whittaker, J.C. 1994. Flintknapping: Making and Understanding Stone tools. Austin University of Texas Press. The following articles give a good overview of, and references about the topic: Andrefsky, W. Jr. 2009. The analysis of stone tool procurement, production and maintenance. Journal of Archaeological Research 17 .