ARK2/API - Revision history

John Layt: /* API */

2017-01-05T22:16:47Z

‎API

John Layt: /* API */

2017-01-05T13:58:19Z

‎API

John Layt: /* API */

2017-01-05T13:55:29Z

‎API

John Layt: /* API */

2016-11-30T10:58:24Z

‎API

John Layt: /* API */

2016-11-29T19:55:35Z

‎API

John Layt: /* Query Parameters */

2016-11-29T19:52:41Z

‎Query Parameters

John Layt: /* Query Parameters */

2016-11-29T19:51:53Z

‎Query Parameters

John Layt at 19:40, 29 November 2016

2016-11-29T19:40:32Z

John Layt: Created page with "= API = An evolution of the ARK data model and API to try realise the [http://ark.lparchaeology.com/hypertext/ full ARK vision] will be based arround the Hypermedia concepts..."

2016-10-29T19:30:32Z

Created page with "= API = An evolution of the ARK data model and API to try realise the [http://ark.lparchaeology.com/hypertext/ full ARK vision] will be based arround the Hypermedia concepts..."

New page

= API =

An evolution of the ARK data model and API to try realise the [http://ark.lparchaeology.com/hypertext/ full ARK vision] will be based arround the Hypermedia concepts of [https://en.wikipedia.org/wiki/Representational_state_transfer REST] and [https://en.wikipedia.org/wiki/HATEOAS HATEOAS] as developed by Roy Fielding in his doctoral thesis in 2000. These concepts include resources, relationships, state, and discoverability, and are closely related to the Semantic Web. ARK modules will evolve to represent Resources that can be linked in together in the current flat relationship structure, or organised into configurable hierarchies such as the default Site/Module/Item mostly used by ARK instances. These concepts will be most easily exposed through a RESTful API.

A RESTful API will be implemented using best practices which are outlined in the following articles:
* http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
* http://blogs.mulesoft.com/dev/api-best-practices-series-intro/

In particular, the following rules will be applied:
* Full level 4 [http://timelessrepo.com/haters-gonna-hateoas HATEOAS REST implementation]
* JSON will be the only format supported
* The [http://jsonapi.org/ JSON API] standard will be used to construct the response body, with [http://json-schema.org/ JSON Schema] standard defining the structure of the data payload.
* API versioning will be used to version the resource path structure, error messaging, and other API infrastructure. The actual data formats will be controlled by the JSON schema which will be available via a standard end-point.
* Authenticated access will only be available using HTTPS, API tokens, and OAuth2
* Read-only unauthenticated unencrypted access will be supported only if explicitly enabled
* Translation keys will be used, with the client downloading a translation catalogue for their required language

The general API URL structure will be as follows:
* /api/v2/sites/<site>/<module>/<item>

e.g. for Context MNO12_1 the resource will be www.lparchaeology.com/ark/api/v2/sites/MNO12/contexts/1

A question remains over the structure for hosted ARK installs:
* www.arkhive.org/api/v2/arks/lamas/sites/ABC12/cxt/1 - Allows easy exposure of all instances for LD consumption
* lamas.arkhive.org/api/v2/sites/MNO12/cxt/1 - Easier for migration to stand-alone ARK, more 'private'
* www.arkhive.org/lamas/api/v2/sites/MNO12/cxt/1 - As for 2.

The following HTTP actions will be supported:
* GET - fetch resource
* POST - insert new resource with next available id, i.e. insert a new item with next item number
* PUT - insert or update resource with a specified id, i.e. insert a new item or update an existing item with a set item number
* PATCH - update part of a resource, i.e. update a single field or group
* DELETE - delete a resource
* OPTIONS - What HTTP verbs the current authenticated API user can perform on a resource

The following other endpoints will be supported:
* /filters - The global saved filters
* /filters/123 - The filter definition
* /filters/123/items - The filter result set
* /users - The users
* /users/jlayt - The user details
* /users/jlayt/filters - returns the the list of user filters, etc as per filters endpoint
* /actors - The global actors
* /actors/123 - The actor details

The following query values will be supported:
* ?field1=value1&field2=value2 - basic search in fields (use /filters for advanced search)
* ?sort=field1,field2 - sorts results by fields
* ?fields=field1,field2 - return selected fields
* ?page=3&per_page=100 - pagination of results
* ?q=text - free-text search

Notes:
*Updating a resource will require some kind of timestamp or last update key to prevent overwriting subsequent changes
* All security / OPTIONS / anon access will be controlled by user roles

JSO Schema Implementations:
* JSON Schema validation via PHP League (simple, complete, extendable) or Justin Rainbow (most widely used)

JSON-API Implementations:
* http://fractal.thephpleague.com/ PHP League Fractal library to serialize as JSON-API - nice, multi-format, but missing some needed features
* https://github.com/woohoolabs/yin - Very nice but PSR-7 and JSON Schema validation uses Rainbow, 5 contrib, 29 releases, last update 2 weeks
* https://github.com/tobscure/json-api - Good, clean, complete standard, agnostic, but no extras/schema/header handling. 17 contrib, 5 releases, last update 1 month, 2nd popularity rank
* https://github.com/neomerx/json-api - 7 contribs, 42 releases, last update 1 week
* https://github.com/nilportugues/php-json-api - 8 contribs, 63 releases, last update 3 weeks
* https://github.com/nilportugues/symfony-jsonapi - Symfony 2 bundle, last update 2 weeks
* https://github.com/mauro-moreno/silex-jsonapi - Silex provider for nilportugues, ast update 2 months
* https://github.com/lode/jsonapi - Simple, 2 contrib, 10 releasses, last update 3 weeks
* PHP Client: https://github.com/Art4/json-api-client

Not considered:
* https://github.com/matthiasbayer/json-api - 1 contrib, last update 1 year
* https://github.com/matthiasbayer/BayerJsonApiBundle - Symfony2 bundle,1 contrib, last update 1 year
* https://github.com/rstgroup/json-api-php - 3 contrib, last update 2 years
* https://github.com/GoIntegro/hateoas deep symfony integration, would be ideal but is driven by Doctrine ORM map and RAML

@@ Line 3: / Line 3: @@
 ARK2 provides a new, standards-compliant, secure, complete API for query and update.
-A number of popular API standards exits. ARK2 has chosen JSON:API as the default API standard, as this is the best suited to the full update functionality required by external apps. However, given the very large user base for JSON-LD within the heritage community, support will be added for it in read-only mode. The library used for JSON-LD will also provide HAL, JSON, and CSV standards support. Facebook's [http://graphql.org/ GraphQL] will be considered in the future.
+A number of popular API standards exits. ARK2 has chosen JSON:API as the default API standard, as this is the best suited to the full update functionality required by external apps. However, given the very large user base for JSON-LD within the heritage community, and Google's use of it for SEO, support will be added for a read-only API and semantically-tagged HTML. The library used for JSON-LD will also provide HAL, JSON, and CSV standards support. Facebook's [http://graphql.org/ GraphQL] will be considered in the future.
 == Background ==

@@ Line 3: / Line 3: @@
 ARK2 provides a new, standards-compliant, secure, complete API for query and update.
-A number of popular API standards exits. ARK2 has chosen JSON:API as the default API standard, as this is the best suited to the full update functionality required by external apps. However, given the very large user base for JSON-LD within the heritage community, support will be added for it in read-only mode. The library used for JSON-LD will also provide HAL, JSON, and CSV standards support.
+A number of popular API standards exits. ARK2 has chosen JSON:API as the default API standard, as this is the best suited to the full update functionality required by external apps. However, given the very large user base for JSON-LD within the heritage community, support will be added for it in read-only mode. The library used for JSON-LD will also provide HAL, JSON, and CSV standards support. Facebook's [http://graphql.org/ GraphQL] will be considered in the future.
 == Background ==

← Older revision		Revision as of 13:55, 5 January 2017
Line 1:		Line 1:
	= API =		= API =
		+
		+	ARK2 provides a new, standards-compliant, secure, complete API for query and update.
		+
		+	A number of popular API standards exits. ARK2 has chosen JSON:API as the default API standard, as this is the best suited to the full update functionality required by external apps. However, given the very large user base for JSON-LD within the heritage community, support will be added for it in read-only mode. The library used for JSON-LD will also provide HAL, JSON, and CSV standards support.
		+
		+	== Background ==

	An evolution of the ARK data model and API to try realise the [http://ark.lparchaeology.com/hypertext/ full ARK vision] will be based arround the Hypermedia concepts of [https://en.wikipedia.org/wiki/Representational_state_transfer REST] and [https://en.wikipedia.org/wiki/HATEOAS HATEOAS] as developed by Roy Fielding in his doctoral thesis in 2000. These concepts include resources, relationships, state, and discoverability, and are closely related to the Semantic Web. ARK modules will evolve to represent Resources that can be linked in together in the current flat relationship structure, or organised into configurable hierarchies such as the default Site/Module/Item mostly used by ARK instances. These concepts will be most easily exposed through a RESTful API.		An evolution of the ARK data model and API to try realise the [http://ark.lparchaeology.com/hypertext/ full ARK vision] will be based arround the Hypermedia concepts of [https://en.wikipedia.org/wiki/Representational_state_transfer REST] and [https://en.wikipedia.org/wiki/HATEOAS HATEOAS] as developed by Roy Fielding in his doctoral thesis in 2000. These concepts include resources, relationships, state, and discoverability, and are closely related to the Semantic Web. ARK modules will evolve to represent Resources that can be linked in together in the current flat relationship structure, or organised into configurable hierarchies such as the default Site/Module/Item mostly used by ARK instances. These concepts will be most easily exposed through a RESTful API.

@@ Line 17: / Line 17: @@
 The general API URL structure will be as follows:
-* /api/v2/sites/<site>/<module>/<item>
+* /api/v2/<module>/<item>/<submodule>/<item>
-e.g. for Context MNO12_1 the resource will be www.lparchaeology.com/ark/api/v2/sites/MNO12/contexts/1
+e.g. for Site MNO12 and Context MNO12_1 the resource will be www.lparchaeology.com/ark/api/v2/sites/MNO12/contexts/1
 A question remains over the structure for hosted ARK installs:
@@ Line 44: / Line 44: @@
 * /actors/123 - The actor details
-The JSOn:API query values will be supported:
+The JSON:API query values will be supported:
 * ?filter - basic search in fields (use /filters for advanced search)
 * ?sort - sorts results by fields
@@ Line 52: / Line 52: @@
 Notes:
-*Updating a resource will require some kind of timestamp or last update key to prevent overwriting subsequent changes
+* Updating a resource will require some kind of timestamp or last update key to prevent overwriting subsequent changes
 * All security / OPTIONS / anon access will be controlled by user roles

@@ Line 95: / Line 95: @@
   ()	Grouping
   []	In
+ ''	Literal string
 For example:

@@ Line 44: / Line 44: @@
 * /actors/123 - The actor details
-The following query values will be supported:
+The JSOn:API query values will be supported:
-* ?field1=value1&field2=value2 - basic search in fields (use /filters for advanced search)
+* ?filter - basic search in fields (use /filters for advanced search)
-* ?sort=field1,field2 - sorts results by fields
+* ?sort - sorts results by fields
-* ?fields=field1,field2 - return selected fields
+* ?fields - return selected fields
-* ?page=3&per_page=100 - pagination of results
+* ?page - pagination of results
-* ?q=text - free-text search
+* ?q - not standard, free-text search?
 Notes:

@@ Line 94: / Line 94: @@
   ;	And
   ()	Grouping
 TODO: In
@@ Line 99: / Line 100: @@
 For example:
-  &filter=foo==3,foo==5;bar=@bong
+  &filter=foo==3,foo==5;bar=@bong;magic[this,that,other]

← Older revision		Revision as of 19:40, 29 November 2016
Line 74:		Line 74:
	* https://github.com/rstgroup/json-api-php - 3 contrib, last update 2 years		* https://github.com/rstgroup/json-api-php - 3 contrib, last update 2 years
	* https://github.com/GoIntegro/hateoas deep symfony integration, would be ideal but is driven by Doctrine ORM map and RAML		* https://github.com/GoIntegro/hateoas deep symfony integration, would be ideal but is driven by Doctrine ORM map and RAML
		+
		+	== Query Parameters ==
		+
		+	The JSON:API standard does not specify how to structure filter/search query parameters, other than to define 'filter=' for this purpose. The following standard, based mainly on [https://developers.google.com/analytics/devguides/reporting/core/v3/reference#filters Google APIs], is used.
		+
		+	Operators (must be encoded where appropriate):
		+	== Equals/ Exact match
		+	!= Does not equal / Does not match
		+	> Greater than
		+	< Less than
		+	>= Greater than or equal to
		+	<= Less than or equal to
		+	=@ Contains substring
		+	!@ Does not contain substring
		+	=~ Contains a match for the regular expression
		+	!~ Does not match regular expression
		+	! Not
		+	, Or
		+	; And
		+	() Grouping
		+
		+	TODO: In
		+
		+	For example:
		+
		+	&filter=foo==3,foo==5;bar=@bong