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.

When working with SmartObjects it's important to know how properties are used for the service. For example, if you have a POST method that requires you to submit a complex object type (entity) you must first serialize that entity using its serialization method before you can call the POST method. The serialized string representing the required entity is passed as a string property containing a serialized object to the method. This method of representing complex types as serialized objects is common to many service brokers that K2 ships out of the box, so if you're already familiar with these principles you can apply them to the REST broker.

If you're not familiar with these concepts, use the example below that uses a sample Swagger Pet Store service.

Some points to bear in mind if you are working through this sample:

  • Use the example PetStore.json descriptor file to register the Service Instance
  • The Swagger PetStore service automatically deletes pets created as part of this example service so you should call the FindPetsByTags method soon after creating the pet, otherwise you may not find it if the method is called at a later time.
  • The Swagger PetStore service changes as the development of Swagger continues. Examples used here and the structure of the service may not match what you see.

Using the Pet Store example, there is an AddPet method on the Pet entity that requires a Pet memo field to execute:

Executing the Serialize method of the Pet entity requires the following properties:

The Category, PhotoUrls and Tags properties are entities as well, so in order to call the Serialize method of the Pet entity you must first serialize those entities. Note that the descriptor file does not contain an entity for PhotoUrls since it is an array of strings. It is an optional property it is not included in the example.

The Serialize method of Category requires an ID and a Name:

Executing the method returns a serialized string which can then be used as the value for the Category property of the Serialize method of the Pet entity.

  • Any field that is of type Memo typically represents a complex type that needs to be serialized.
  • If a field can contain multiple items, such as Tags, two square brackets follow the entity name, e.g. Tags[]. This means that you must run the Serialize Item to Array method instead of the Serialize method.

  • If a serialized item is an array of items you would use the Deserialize Array or Deserialize Typed Array to extract values from the serialized string returned from the service.

When you have all of the serialized strings ready you can use them to create a Pet object, as follows:

Once you have the Pet object serialized you can pass that in to the AddPet method as a single input. Executing the method returns an HTTP response code of 200, confirming that the pet was added.

To find the ID of the pet you can use the FindPetsByTags method of the Pet entity. This method requires a serialized array of strings, so you use the Serialize Item to Array method of the String System Type to generate a serialized string:

You can then pass the serialized array in to the FindPetsByTags method as follows:

In the screenshot above, you can see that Bowzer was created with ID 1433767701761.

There are simple types (Id, Name and Status) returned by this method as well as complex types that are serialized. To deserialize these complex types, such as Category, you execute the Deserialize method of that entity. For example:

Lastly, you can create an advanced SmartObject that chains these serialize & deserialize methods. For more information about doing this, see Working with Endpoint SmartObjects.

For example purposes only, here are the following serialized strings used in the sample:

  • Category for Serialize method of Pet: {"$type":"PetStore.Category, PetStore, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","id":4857,"name":"Dogs"}
  • Tags for Serialize method of Pet: {"$type":"PetStore.Tag[], PetStore, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"PetStore.Tag, PetStore, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","id":234234,"name":"MyPet"}]}
  • Pet for AddPet method of Pet: {"$type":"PetStore.Pet, PetStore, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","id":0,"category":{"$type":"PetStore.Category, PetStore, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","id":4857,"name":"Dogs"},"name":"Bowzer","photoUrls":null,"tags":{"$type":"PetStore.Tag[], PetStore, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","$values":[{"$type":"PetStore.Tag, PetStore, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null","id":234234,"name":"MyPet"}]},"status":"Available"}
  • String Array for tags parameter of FindPetsByTags method of Pet: {"$type":"System.String[], mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089","$values":["MyPet"]}

Considerations