Advanced REST Web API Overview

Overview

CIS Infinity Version 4 is equipped with a standardized API utilizing the REST (Representational State Transfer) architectural style. This architecture presents a RESTful or REST like interface and is defined by constraints that must be met. These constraints will be described later.

The Advanced RESTful Web API (API) is fully documented and published using Swagger, which allows discovering, testing, and prototyping the API. The API supports JSON inputs and outputs, paging and data shaping.

Note: All core business logic available in CIS Infinity – ranging from processing a meter change at an account to retrieving complex billing data – will eventually be accessible in the published REST API for external access. (third party company)

Internally used by CIS Infinity and CIS add-ons, the API provides external vendors with the ability to create their own applications that communicate with and/or insert entries into CIS Infinity, as well as allows using alternative user interfaces to write their applications.

The subsequent sections describe how the Advanced RESTful Web API is designed and functions, with specific examples. Use these examples to assist with determining how to call the necessary API services that will perform the functions you want in CIS Infinity.

Software Requirements

• .Net Version 4.7.2 or higher. This facilitates the use of Web API 2 (built on ASP MVC5) and asynchronous constructs.

• IIS 7.5 or later

• ASP.NET 4.7.2 or later

Application Architecture and Implementation

The API architecture is established from the Advanced Utility Services API layer (Services API), and resource models. Model properties correspond directly with the CIS Infinity Business Class equivalents (customer, account, address, etc.), and the Uniform Resource Identifiers (URIs), which are considered resources, never change.

Resource Names in the API are the Business Class Names (e.g. CustomerAccount) from the CIS Infinity Services API, and the unique API RESTful Resource ID values are the unique and mandatory O_Code values (e.g. CUSTACCTID) associated with each business object in the CIS Infinity Services API.

Note: There are several ways to determine the CIS Business Class Names and associated O_Code to call in the API:

• In CIS Infinity:

  • Access the Class Name using the CIS Form Lookup form

  • Using the right-click menu, click on the Support Info menu option

• Use the Advanced REST Web API documentation

• Use the Swagger documentation

Security and login features are implemented using the Authentication Header in the API and API access is protected using the CIS Infinity V4 security model at the business object layers.

All data updates are passed through the services layer, ensuring that data integrity is maintained and the business layer security is protected.

Authorization and Authentication

Installation and use of the API requires HTTPS/SSL certificate security. The website where the API is hosted can use a self-signed certificate if desired by the organization. Acquiring, installing, and distributing SSL certificates is the responsibility of the client.

API call authorization and authentication is done using a standard HTTP Basic Authorization using the Authorization header.

Tools

The API was programmed using MS ASP.NET Web API 2 and there are several tools available for clients to choose from to test and document the API. Some tools are listed here:

• curl – A command line client used to produce automated testing scripts. Can be used in conjunction with Postman, which also generates curl commands.

• Fiddler – Web debugging proxy tool.

• Postman – A popular REST client. An API development and experimentation environment. This is the tool we use most often internally at Advanced.

• Insomnia – Another popular REST client.

• PowerShell – A great interactive scripting tool for experimenting with the REST API.

• Swagger – (aka OpenAPI Specification or OAS) Used for discoverability and self-documentation of the API.

• NSwag – NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, .NET Core, Web API, ASP.NET Core, TypeScript (jQuery, AngularJS, Angular 2+, Aurelia, KnockoutJS and more) and other platforms, written in C#. .

REST Constraints

REST Constraints are rules that are applied to establish the distinct architectural design of a RESTful API. The following constraints were implemented for the REST API:

Cacheable

The response messages from the API services to the client are cacheable at the Internet and/or HTTP (Hypertext Transfer Protocol) level. Caching allows the client or intermediate HTTP servers in the HTTP chain to cache the server data, if appropriate. This is very important for performance and scalability.

When using HTTP, caching can occur automatically by setting the appropriate header tags, which indicate that the data can be cached by the HTTP, under what conditions, and the length of time allowed for caching. This is useful for situations where multiple requests might be made to the same data resource by different clients, and if caching applies, the CIS application may be bypassed and will not see the request because the cache was supplied by the inter-webs.

Client Server

This establishes a clear separation between the web services and the clients / consumers, and provides the services based on the requests that are made.

Stateless

The API server maintains no state about the client. This means the communication between the client and server involves no session objects, and each call to the server is independent of the call that occurred before and after. This is beneficial when considering scalability and caching. Typically implementing this feature is more difficult when dealing with a thick client application, such as CIS Infinity.

Layered System

There are multiple architectural layers and no one layer has focus past the next. This facilitates middleware components and layers can be added, removed, modified or reordered according to the requirements for the API.

Uniform Interface

When considering that the REST API adheres to a uniform interface, it implies the following:

• Uniform Resource Identifiers – All API services and clients within the REST-compliant architecture share a single, overarching technical architecture. Uniform Resource Identifiers (URIs) are considered resources, which are unique and will never change (permanent).

• Manipulation of resources through their presentations – Interaction with each resource is done through Swagger (or another tool) by running calls against CIS Infinity using the HTTPS (HyperText Transfer Protocol with Secure Sockets Layer) implementation. This implementation allows performing actions using the standard HTTP methods with appropriate parameters specified in the call. The standard methods for REST are as follows:

  • GET – Retrieves the list of resources or an individual resource.

    Example:

    URL path: 'https://yourApi/data/resourceName'

    URL path: 'https://yourApi/data/resourceName/id'

    Authorization: Your CIS user name and password

  • POST – Adds a new resource. Note that business validation is applied and any issues are reported with a 400/Validation failed response. Missing properties are defaulted to blank/empty.

    Example:

    URL path: 'https://yourApi/data/resourceName'

    Authorization: Your CIS user name and password

    Headers: 'Content-Type' 'application/json'

    Body: '{ "description":"newDescription", "code": "AA"}'

  • PUT – Updates the entire individual resource only. Missing properties are defaulted to blank/empty. Business rules are applied and issues reported via 400/Validation failed response.

    Example:

    URL path: 'https://yourApi/data/resourceName/id'

    Authorization: Your CIS user name and password

    Headers: 'Content-Type' 'application/json'

    Body: '{ "description":"newDescription", "code": "AA"}'

  • DELETE – Deletes the resource.

    Example:

    URL path: 'https://yourApi/data/resourceName/id'

    Authorization: Your CIS user name and password

  • PATCH – Performs a partial update to the resource typically based on a limited list of modifications and new values (using the mechanisms defined by JSONPatch RFC6902). This list can be used to add, update or delete part of a resource. Patch syntax is different from other requests. Since patch is a partial update, it should contain information about particular field within the model which should be updated. Also, it should contain patch operations, such as 'replace', 'add' or 'remove' and new value for updating field. More information here: link.

    Example:

    URL path: 'https://yourApi/data/resourceName/id'

    Authorization: Your CIS user name and password

    Headers: 'Content-Type' 'application/json'

    Body: '[{ "op": "replace", "path": "/description", "value": "this is a description" }, { "op": "replace", "path": "/o_customdata/myflag", "value": true }]'

  • VALIDATE – An Advanced extension custom method which validates the target resource or the given resource changes. This is an Idempotent and safe method, which will not affect database and needed for evaluation purposes.

    Example:

    URL path: 'https://yourApi/data/resourceName'

    Authorization: Your CIS user name and password

    Body: '{ "description":"newDescription", "code": "AA"}'

    Example:

    URL path: 'https://yourApi/data/resourceName/id'

    Authorization: Your CIS user name and password

  • NEW – An Advanced extension custom method which returns a business object model resource populated with default data as handled by the AddDefaults() function of the standard CIS business object life cycle functionality.

    Example:

    URL path: 'https://yourApi/data/resourceName'

    Authorization: Your CIS user name and password

• Self-descriptive Resource Representation – Resource messages appear in the format requested in the header of the call to the resource. The implemented format for presenting resource messages is JSON. When determining the presentation of the resource message, the format parameters that will typically be included are the full resource, Content-Type, and any other headers, if required.

• HATEOAS “ Hypermedia As The Engine Of Application State”, promotes the linking of resources to each other and to operations available on them in useful and dynamic ways. This results in resources that contain links to related resources. The Advanced Web API implements this using the “HAL” standard, which makes the API much more self-documenting than other types.

API Design

This API Design table explains how the HTTP methods affect Resource URIs in the API. Currently, only the Resources (URIs) listed with “/data/” are implemented.

List Result Details

All list level resource GET results conform to the HAL document formatting standard (i.e. JSON). Any request for a return of list results will return a container with several list summary and status information, along with the requested list. The list container will be a wrapper for the list and have a standard structure, as follows:

• “ totalItems” count – This is the total number of items in the entire list.

• “ pagesSize” value – This value indicates the standard number of items in a page, and therefore the number of items in this result, unless it is the last/only page.

• “ totalPages” value – This value indicates the total number of pages in the entire list.

• “ currentPage” value – The number of the current page.

Note: The HATEOAS _link items “next” and “prev” will also be available if applicable to point to the previous or next page of the list.

Example Request:

https://localhost/data/account?pagesize=20&page=3&order=accountnumber&fields=*&where=accountnumber gt '00011111' and accountnumber lt '00099999'

Batched Requests

Multiple individual HTTP REST requests can be packaged into a single request message by using the MIME (RFC1341) standard multipart message format and sending a POST to the /batch endpoint:

• Each request is processed and transactioned independently of the others; requests are not transactioned as a group.

• A content type of "multipart/mixed" indicates that the requests should be processed sequentially. This guarantees that each is finished before the next starts. Each is processed in the order in which they appear in the request.

• A content type of "multipart/parallel" indicates that the requests can be processed in parallel, if possible. Parallel processing is not guaranteed. They may be processed sequentially, or in parallel, in any order.

• Individual response content are always placed in the same order as the requests in the response MIME multipart body.

• An HTTP response is not returned until all requests are finished.

• An authorization header is required on the main request and must be valid. Individual requests can include an authorization header if desired. Individual authorization headers will apply to the message on which it is applied and override the default from the main authorization header. If individual requests do not have an authorization header, then the main header credentials will apply.

• Response content type will be the same multipart content type as the request.

Example Request:

HTTP text representing a sample batch request is available here.

API Versioning

Any functionality that is deemed to need versioning will have version support added and will interpret the “version” query string as requesting a specific version of that URI. By default, the latest version is always used if a version is not requested. Versioning will only be supported on URIs where a change is made that potentially breaks functionality, and/or the existing functionality will be required by a client. Examples of changes that could require versioning are the removal of a field or parameter, or changes to an existing function, which causes it to behave very differently.

Note: Versioning will not be implemented when a new field is added to an existing item, or new or additional functionality is added to an existing item, or when functionality changes or additions are only enabled by optional configuration elsewhere in CIS Infinity.

Query Strings

The HTTP URL supports a variety of query strings to shape the data and to control aspects of the operation. Consider using the following query strings:

Common Status Codes

The various status codes that can occur when using HTTP methods are listed in the following table:

Common Status Codes by HTTP Method

The common status codes that can occur when using HTTP methods are listed in the following table:

See RFC7231 for more details and standards around HTTP verbs and response codes.

Header Tags

Common header tags that apply to the API requests:

See RFC7231 Request Headers for more details on these and other HTTP headers.

Custom Field and Table Support

CIS custom fields functionality is completely supported through the REST interface. Every return business model contains an additional container property o_CustomData with properties corresponding to each custom field and value associated with that resource.  Each custom field item defined on the resource is included with its current value. Property names and values are formatted exactly like all other object properties.

Note that PUT/POST handling for custom properties is slightly different from the standard properties:

• If the o_CustomData container is not included in the PUT/POST object, the custom properties are not touched. This means existing values are left unchanged on an update, and new values are defaulted on an add.

• If the o_CustomData container is included, then only explicitly included properties in the container are handled. Missing properties are not touched on an update, and defaulted on an add. This is different from base property handling where any missing properties are always set to the default value on add and update.

Note that PATCH support is slightly different for custom properties. The path reference in the PATCH command should be formatted as "/O_CustomData/MyPropertyName" rather than just the property name alone as with standard properties.

    Example:

    PATCH ../data/serviceorder/901950

    [
      {"op":"replace","path":"/serviceMessage","value":"BIF023 has Custom Fields"},
      {"op":"replace","path":"/o_customdata/test","value": true},
      {"op":"replace","path":"/o_customdata/topfigure","value": 3.5}
    ]

Logging

The Advanced Web API REST server has the ability to log system messages as well as request/response details. The logging is configured via settings in the NLOG.config file in the Advanced Web API home folder. Examples and additional documentation are available in the NLOG.config.sample file, also in the Web API home folder. Documentation on unusual or advanced logging configurations can be found at the NLOG website.

System Log

The system log name is WebApi and records any system level events, messages, and errors. It logs levels Debug, Info, Warn, and Error. Debug level messages are verbose and log internal functionality typically around session and cache management and operations. Info level messages record normal system operations like start up and shutdown and requests for system actions like enabling, disables, or recycling, the server. Warn and Error level messages are important and should be reviewed and addressed immediately.

Request/Response Logs

Web API has the ability to record detailed information about any requests and responses handled by the server. Details such as request user, URI, method, and payload can be selected. Response details can also be tracked for each request, including response code, message, and payload. Care should be taken when selecting request or response payload logging, since it imposes a heavy load on the server and the logger. Requests can be filtered based on method, URI, and response code.

Request/response logger configuration is done with a logger item of the form: <logger name="[method pattern]:[URI pattern]" levels="[levels]" writeTo="[target]" />

[method pattern]

HTTP method verb(s) that this logger activates. Available verb names are GET, PUT, POST, PATCH, DELETE, VALIDATE, and NEW. Multiple verbs can be combined by using "," or "|" separators. Required; use "*" to match all verbs.

[URI pattern]

URI path that this logger applies to. Only one path can be specified, but a trailing wildcard "*" character can be used to match all child paths. A leading "/" is optional and implied if missing. "/data/sta*" would match paths "/data/state" and "/data/station". and all children of them, while "/data/state/*" would only match that exact path and its children. Required; use "*" to match all paths.

[levels]

Selects the logging levels to activate for. Comma separated list of one or more of: Debug, Info, Warn, Error. Debug = 2xx messages; Info = 1xx/3xx messages; Warn = 4xx messages, and Error = 5xx messages. Can use NLOG directive 'minlevel' instead.

[target]

Reference to the NLOG <target> item that will format and emit this logger item.

Additional logger target layout items are available to access the specialized data associated with a request and response. These layout items are accessed using a layout= attribute on the target definition and have the form layout="${event-properties:[keyword]}" where [keyword] is one of the following: User, UserIp, HttpMethod, RequestUri, RequestPath, RequestQueries, RequestHeaders, Status, ElapsedTime, RequestBody, ResponseBody

Sample NLOG configuration file

Additional Documentation About Advanced Business Functions

• Advanced searching using $search or /data/customeraccount/search

• Performing a Move In/Out using /data/customeraccount/move

• Meter operations (change/modify/install/remove) using /data/accountmeter/change

Web API Code Examples and Resources

Sample code for HTTP requests provided using different programming languages. This is a sample code, which interacts with CIS classes and provides GET, PUT, POST, DELETE, PATCH, VALIDATE methods

• C# sample code to Get/Post/Put/Delete a resource (and corresponding Visual Studio 2017 project)

• Java sample code to GET/POST/PUT/DELETE/PATCH a resource

• Python sample code to GET/POST/PUT/DELETE/PATCH a resource

• PowerShell sample code to Get/Post/Put/Delete a resource

• JaveScript sample code to Get/Post/Put/Delete a resource

• PowerShell sample to retrieve a list from any given resource

• .NET WebApi Models library DLL associated with this version

• Sample HTTP / JSON for a typical PATCH request

• Sample HTTP for a batched request to the /batch endpoint

• C# sample code for a batched request to the /batch endpoint

• JavaScript ECMA6 REST model definitions (commented, one file per model, zipped, for reference/documentation)

• TypeScript REST model definitions (commented, one file per model, zipped, for reference/documentation)

• JavaScript ECMA6 REST model definitions (minified, combined, for use as script reference in third party HTML)

Getting Started with the published OpenAPI using Swagger

• After the REST Web API is installed, use this URL to access the Swagger UI from a web browser: /swagger

• You can retrieve an up-to-date Swagger/OpenAPI document for this system from the resource /swagger/docs/v1