REST

The REST Service Type is used to allow K2 to integrate with REST endpoints, by exposing a particular REST endpoint as a service instance and then creating SmartObjects that utilize the service objects exposed by the service instance.

The REST Service Type is a little more advanced than other Service Types, and requires some knowledge of REST, endpoints, entities, HTTP methods and serialization/deserialization

The REST broker is unlike other service brokers in that it does not discover entities and methods of the LOB system (in this case the REST endpoint) when a Service Instance is registered. Instead, when registering the service instance, you must provide a descriptor file in Swagger format that describes the entities and methods in the targeted endpoint. This descriptor file will control how the Service Objects for entities and methods (paths) in the endpoint are generated. (For more information about Swagger see http://swagger.io/ and the REST Swagger File Reference Format topic.)

For more information and practical examples on using the REST Service Broker, please see the following series of K2 Knowledge Base Articles:

Querying and submitting data using an Endpoint Service Type can be a complex issue. It requires a good understanding of data and how it is returned from the service call. It also requires understanding the serialization and deserialization methods that are intrinsic to the .NET Framework.

The main methods that are used with the endpoint services are Serialization and Deserialization. Simply put, these methods are used to send and store complex data. To Serialize the results of a service call means to represent it in a state that can be transferred and/or stored, such as in a database. To Deserialize that data is to turn it back into a state that can be consumed. These methods, while based on the .NET Framework for the purposes of the K2 Endpoint Service Type, represent a device-independent, cross-platform method of representing complex, relational data.

Prerequisites

To use a REST Service Instance you must first generate the Swagger descriptor file, and register an OAuth resource in K2 if your endpoint requires OAuth. For the sample PetStore.json file given later in this topic you do not have to establish an OAuth resource.

Service Authentication

All available Authentication Modes are supported by this broker. The Authentication Mode of the Service Instance should be set according to the authentication required by the endpoint. For example, if the endpoint supports static authentication then select the static authentication mode and provide a username and password.

The same authentication mode used for the Service Instance will also be used to access the DescriptorLocation .json file when that file is located in a URL.

If using the OAuth Authentication Mode, bear the following points in mind:

Service Keys (Service Instance Configuration Settings)

The following table lists the Service Keys, their default values and some sample values. The sample values use the PetStore service at http://petstore.swagger.io/. You can download a pre-defined descriptor file for this sample from http://help.k2.com/repository/staticfiles/global/en/petstore.json.

Key Can be modified Data Type Sample Value Notes
Serialization: Include All Assembly types Yes True/False True
(Default value: True)

Includes all available serialization objects regardless of usage in public methods.

Default Http Request Headers Yes Text {"$type":"SourceCode.SmartObjects. Services.Endpoints.Common.HttpHeader, SourceCode.SmartObjects.Services. Endpoints.Common, Version=4.0.0.0, Culture=neutral, PublicKeyToken=null","Name": "nameExample","Value":"valueExample"} (sample) Used to supply default HTTP headers that should be added onto every HTTP request. This key is a name/value pair that is serialized using the HttpHeader system type as shown below in The HttpHeader Type section. An example of an HttpHeader value might be an additional authentication name/value pair required by the service.
Descriptor Location Yes Text c:\petstore.json (see a sample)

Required. The location of the descriptor file. This can either be the full path to file on the local hard drive or a URL.

The Authentication Mode used for the Service Instance will also be used to access the DescriptionLocation .json filer when that file is located using a URL.

This file must be available at this location whenever the Service Instance is refreshed.

Names: Append Property Types Yes True/False True
(Default value: True)

Includes the property type in parentheses after the complex property name.

Certificate Store Location Yes Text CurrentUser
(Default value: CurrentUser)

This config setting is only used when the Certificate Search Value config setting is not set to null.

The location of the certificate store to open. The valid config values are CurrentUser and LocalMachine. Please refer to:http://msdn.microsoft.com/enus /library/system.security.cryptography.x509certificates.storelocation.aspx for more information.

Break on Error Yes True/False False
(Default value: False)

When True displays an error dialog if calling the service results in a non-success response. When False no error is displayed. In either case the HttpResponseCode return property contains any errors.

Debugging Enabled Yes True/False False
(Default value: False)

Displays stack trace information in dialog and error information.

Certificate Search Value Yes Text NameOfCertificate (sample)
(Default value: null)

The search value to use when looking for a client certificate. Filling in this config setting will cause the broker to expect to find a valid certificate at the specified location. An error will be thrown if a valid certificate is not found (this includes the case where a certificate is found, but the certificate is invalid due to expiration or lack of trust). Used in conjunction with the Certificate Search Method and Certificate Store Name Service Keys.

Add HTTP Response Header Property To Methods Yes True/False True Adds an optional property to each method to allow for a list of HTTP Response headers to be returned from the service.
Certificate Search Method Yes Text FindBySubjectName
(Default value: FindBySubjectName)

This config setting is only used when the Certificate Search Value config setting is not set to null.

The method with which to search the opened certificate store for the client certificate. There are a number of search options available including searching by name or thumbprint.

Please refer to:http://msdn.microsoft.com/enus/library/system. security.cryptography.x509certificates.x509findtype.aspx for a complete list of all valid config values.

Names: Use Method FullName Yes True/False True
(Default value: True)

Uses the full name of the method including the property names and types.

Certificate Store Name Yes Text My
(Default value: My)

This config setting is only used when the Certificate Search Value config setting is not set to null.

The name of the certificate store under which the client certificate is installed. The valid values for this config setting are: AddressBook, AuthRoot, CertificateAuthority, Disallowed, My, Root, TrustedPeople, and Trusted Publisher. Please refer to: http://msdn.microsoft.com/enus/library/system.security. cryptography.x509certificates.storename.aspx for more information.

As of time of writing, the REST Broker has only been tested with the My certificate store.

Add HTTP Request Header Property To Methods Yes True/False True Adds an optional property to each method to allow for a list of HTTP Request Headers to be sent to the service.
Serialization: Compress Yes True/False False
(Default value: False)

Compress the serialization data for complex types.

Service Objects

Once an Endpoints REST Service Instance has been created, the entities and service operations described by the descriptor file are represented as Service Objects.

The Service Types are grouped into the following categories:


The HttpHeader Type

The HttpHeader system type is a special type of service object that is used to serialize or deserialize name/value pairs for the Service Instance or for individual methods. To use this type you must generate a SmartObject from the service object and then call a method on the SmartObject. When specifying this header you execute the Serialize method on the HttpHeader object and use the serialized value as shown in the Service Keys table above. If you need more than one HttpHeader you serialize each name/value pair and then use the Serialize Add Item to Array method for each name/value pair that needs to be passed to the endpoint.

SmartObjects

K2 does not automatically create SmartObjects for the Service Objects in this service. SmartObjects are automatically created when selecting the Generate SmartObjects for this Service Instance check box when creating a new Service Instance. Designers may use the available Service Objects in this service to create advanced SmartObjects using the available K2 SmartObject design tools. It is recommended to use the K2 Design tools to create SmartObjects rather than generating SmartObjects, since this allows better control over the naming, behavior and design of the SmartObject and its methods and properties.

Considerations