REST API - Revision history

Craig at 19:38, 7 June 2023

2023-06-07T19:38:34Z

← Older revision		Revision as of 19:38, 7 June 2023
Line 109:		Line 109:
	== Serializing & Deserializing Date Types ==		== Serializing & Deserializing Date Types ==

	Since the Obsidian REST API uses its own specific date formats to fully represent scheduled times including their time zones, you will have to use custom serializers to properly use the supplied bean classes. Doing this is simple, and we've provided a sample below for [https://~~code.google~~.com/p/~~google-~~gson/ Gson], plus a generic example to show you how to parse and format dates appropriately, which you can adapt for use in JSON other libraries.		Since the Obsidian REST API uses its own specific date formats to fully represent scheduled times including their time zones, you will have to use custom serializers to properly use the supplied bean classes. Doing this is simple, and we've provided a sample below for [https://github.com/google/gson Gson], plus a generic example to show you how to parse and format dates appropriately, which you can adapt for use in JSON other libraries.

	'''GSON Serialization:'''		'''GSON Serialization:'''

Craig at 20:58, 17 May 2023

2023-05-17T20:58:45Z

← Older revision		Revision as of 20:58, 17 May 2023
Line 101:		Line 101:
	As of version 2.3, Obsidian comes bundled with simple bean classes in the package <code>com.carfey.ops.api.bean</code> that can be used to serialize JSON requests and deserialize responses into plain old Java objects (POJOs). These bean classes are located in <code>obsidian.jar</code> which is included in your Obsidian zip download within the <code>standalone</code> directory.		As of version 2.3, Obsidian comes bundled with simple bean classes in the package <code>com.carfey.ops.api.bean</code> that can be used to serialize JSON requests and deserialize responses into plain old Java objects (POJOs). These bean classes are located in <code>obsidian.jar</code> which is included in your Obsidian zip download within the <code>standalone</code> directory.

	These classes are tested with [https://~~code.google~~.com/p/~~google-~~gson/ Gson] since that is what Obsidian uses internally, but you can integrate it with the JSON library of your choosing. Obsidian uses custom types for dates and datetimes, so see the following section on how to configure JSON serialization correctly.		These classes are tested with [https://github.com/google/gson Gson] since that is what Obsidian uses internally, but you can integrate it with the JSON library of your choosing. Obsidian uses custom types for dates and datetimes, so see the following section on how to configure JSON serialization correctly.

	'''Compatibility Note:''' If upgrading to Obsidian 2.5, you will notice that bean classes for requests now use typed enumeration values instead of String values. You may have to make small modifications to your code which uses these classes.		'''Compatibility Note:''' If upgrading to Obsidian 2.5, you will notice that bean classes for requests now use typed enumeration values instead of String values. You may have to make small modifications to your code which uses these classes.

Carfey at 17:50, 1 July 2016

2016-07-01T17:50:25Z

← Older revision		Revision as of 17:50, 1 July 2016
Line 35:		Line 35:
	In some rare cases, users may wish to disable the need for authentication credentials in REST calls.		In some rare cases, users may wish to disable the need for authentication credentials in REST calls.

	This can be done by changing the [[Admin Scheduler Settings ~~4.0~~\|scheduler setting]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.		This can be done by changing the [[Admin Scheduler Settings\|scheduler setting]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.

	'''Note:''' This is not recommended on networks exposed to the Internet, or other non-trusted environments.		'''Note:''' This is not recommended on networks exposed to the Internet, or other non-trusted environments.

Carfey: /* Disabling Authentication */

2016-07-01T16:41:08Z

Disabling Authentication

← Older revision		Revision as of 16:41, 1 July 2016
Line 35:		Line 35:
	In some rare cases, users may wish to disable the need for authentication credentials in REST calls.		In some rare cases, users may wish to disable the need for authentication credentials in REST calls.

	~~As of Obsidian 2.7.1, this~~ can be done by changing the [[Admin ~~System~~\|~~System Parameter~~]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.		This can be done by changing the [[Admin Scheduler Settings 4.0\|scheduler setting]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.

	'''Note:''' This is not recommended on networks exposed to the Internet, or other non-trusted environments.		'''Note:''' This is not recommended on networks exposed to the Internet, or other non-trusted environments.

Carfey: /* Common API Behaviour */

2015-01-21T20:40:54Z

Common API Behaviour

← Older revision		Revision as of 20:40, 21 January 2015
Line 56:		Line 56:
	* If a resource with the specified identifier could not be found, a 404 status code will be returned. For example, this would occur if you attempt to load a job with an ID that does not exist.		* If a resource with the specified identifier could not be found, a 404 status code will be returned. For example, this would occur if you attempt to load a job with an ID that does not exist.
	* If an incorrect method is used on an endpoint (e.g. DELETE on a job runtime), a 405 status code will be returned.		* If an incorrect method is used on an endpoint (e.g. DELETE on a job runtime), a 405 status code will be returned.
	* If no valid basic authentication is provided ~~(see [[REST API]])~~, a 401 status code will be returned.		* If no valid basic authentication is provided, a 401 status code will be returned.
	* If no endpoint exists at the requested path, a 404 status code will be returned.		* If no endpoint exists at the requested path, a 404 status code will be returned.
	* If the Content-Type header of a PUT or POST request is not application/json, a 415 status code will be returned.		* If the Content-Type header of a PUT or POST request is not application/json, a 415 status code will be returned.

Carfey: /* Disabling Authentication */

2014-08-21T01:49:01Z

Disabling Authentication

← Older revision		Revision as of 01:49, 21 August 2014
Line 37:		Line 37:
	As of Obsidian 2.7.1, this can be done by changing the [[Admin System\|System Parameter]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.		As of Obsidian 2.7.1, this can be done by changing the [[Admin System\|System Parameter]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.

	'''Note:''' ~~Do this only in environments that are secure and~~ not exposed to the Internet or other non-~~secure networks~~.		'''Note:''' This is not recommended on networks exposed to the Internet, or other non-trusted environments.

	=Common API Behaviour=		=Common API Behaviour=

Carfey: /* Disabling Authentication */

2014-08-21T01:48:31Z

Disabling Authentication

← Older revision		Revision as of 01:48, 21 August 2014
Line 35:		Line 35:
	In some rare cases, users may wish to disable the need for authentication credentials in REST calls.		In some rare cases, users may wish to disable the need for authentication credentials in REST calls.

	As of Obsidian 2.7.1, this can be done by changing the [[Admin System\|System Parameter]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>.		As of Obsidian 2.7.1, this can be done by changing the [[Admin System\|System Parameter]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.

			'''Note:''' Do this only in environments that are secure and not exposed to the Internet or other non-secure networks.

	=Common API Behaviour=		=Common API Behaviour=

Carfey: /* Disabling Authentication */

2014-08-21T01:47:33Z

Disabling Authentication

← Older revision		Revision as of 01:47, 21 August 2014
Line 35:		Line 35:
	In some rare cases, users may wish to disable the need for authentication credentials in REST calls.		In some rare cases, users may wish to disable the need for authentication credentials in REST calls.

	As of Obsidian 2.7.1, this can be done by changing the [[Admin System\|System ~~parameter~~]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>.		As of Obsidian 2.7.1, this can be done by changing the [[Admin System\|System Parameter]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>.

	=Common API Behaviour=		=Common API Behaviour=

Carfey: /* Authentication & Authorization */

2014-08-21T01:47:21Z

Authentication & Authorization

← Older revision		Revision as of 01:47, 21 August 2014
Line 31:		Line 31:

	Valid [http://en.wikipedia.org/wiki/Basic_access_authentication basic access authentication] must be supplied with every request. Valid API users are authorized to access any REST endpoint.		Valid [http://en.wikipedia.org/wiki/Basic_access_authentication basic access authentication] must be supplied with every request. Valid API users are authorized to access any REST endpoint.

			=== Disabling Authentication ===
			In some rare cases, users may wish to disable the need for authentication credentials in REST calls.

			As of Obsidian 2.7.1, this can be done by changing the [[Admin System\|System parameter]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>.

	=Common API Behaviour=		=Common API Behaviour=

Carfey: /* JSON Bean Classes */

2014-03-16T23:20:07Z

JSON Bean Classes

← Older revision		Revision as of 23:20, 16 March 2014
Line 95:		Line 95:

	These classes are tested with [https://code.google.com/p/google-gson/ Gson] since that is what Obsidian uses internally, but you can integrate it with the JSON library of your choosing. Obsidian uses custom types for dates and datetimes, so see the following section on how to configure JSON serialization correctly.		These classes are tested with [https://code.google.com/p/google-gson/ Gson] since that is what Obsidian uses internally, but you can integrate it with the JSON library of your choosing. Obsidian uses custom types for dates and datetimes, so see the following section on how to configure JSON serialization correctly.

			'''Compatibility Note:''' If upgrading to Obsidian 2.5, you will notice that bean classes for requests now use typed enumeration values instead of String values. You may have to make small modifications to your code which uses these classes.

	Each [[REST Endpoints\|endpoint]] documents the appropriate bean class to use.		Each [[REST Endpoints\|endpoint]] documents the appropriate bean class to use.