From 2d971cbd10418d2209cf06fced658aff7a57610a Mon Sep 17 00:00:00 2001 From: Matthias Kretschmann Date: Fri, 15 Nov 2019 11:09:08 +0100 Subject: [PATCH] add migration guide --- MIGRATION.md | 179 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 8 ++ SQUID_INTERFACE.md | 1 - 3 files changed, 187 insertions(+), 1 deletion(-) create mode 100644 MIGRATION.md delete mode 100644 SQUID_INTERFACE.md diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..3adf787 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,179 @@ +# Migration Guide + +Instructions on how to migrate between breaking versions. + +## 0.8.3 → 1.0.0 + +### DDO structure + +The whole structure of the DDO has been changed based on [OEP-12](https://github.com/oceanprotocol/OEPs/tree/master/12) and [OEP-8 v0.4](https://github.com/oceanprotocol/OEPs/tree/master/8/v0.4) to better accomodate the DDOs to hold additional services, like execution of workflows and algorithms. + +For migrating we only have to deal with the `metadata` service holding the asset metadata, which was restructured too: + +old: + +```json +{ + "service": [ + { + "serviceDefinitionId": "0", + "serviceEndpoint": "http://localhost:5000/api/v1/aquarius/assets/ddo/{did}", + "type": "Metadata", + "metadata": { + "base": { + "name": "Madrid Weather forecast", + "description": "Wheater forecast of Europe/Madrid in XML format", + "dateCreated": "2019-05-16T12:36:14.535Z", + "author": "Norwegian Meteorological Institute", + "type": "dataset", + "license": "Public Domain", + "price": "123000000000000000000", + "copyrightHolder": "Norwegian Meteorological Institute", + "files": [ + { + "index": 0, + "url": "https://example-url.net/weather/forecast/madrid/350750305731.xml", + "contentLength": 1000, + "contentType": "text/xml", + "compression": "none" + } + ], + "categories": ["Other"], + "links": [], + "tags": [] + }, + "additionalInformation": { + "updateFrequency": null, + "structuredMarkup": [] + } + } + } + ] +} +``` + +NEW. Where `main` now holds the non-changable attributes only, everything else has been moved to `additionalInformation`. Likewise, `serviceDefinitionId` is now `index`: + +```json +{ + "service": [ + { + "index": 0, + "serviceEndpoint": "http://localhost:5000/api/v1/aquarius/assets/ddo/{did}", + "type": "metadata", + "attributes": { + "main": { + "name": "Madrid Weather forecast", + "dateCreated": "2019-05-16T12:36:14.535Z", + "author": "Norwegian Meteorological Institute", + "type": "dataset", + "license": "Public Domain", + "price": "123000000000000000000", + "files": [ + { + "index": 0, + "url": "https://example-url.net/weather/forecast/madrid/350750305731.xml", + "contentLength": "1000", + "contentType": "text/xml", + "compression": "none" + } + ] + }, + "additionalInformation": { + "description": "Weather forecast of Europe/Madrid in XML format", + "copyrightHolder": "Norwegian Meteorological Institute", + "categories": ["Other"], + "links": [], + "tags": [], + "updateFrequency": null, + "structuredMarkup": [] + } + } + } + ] +} +``` + +Those changes require updates to your code whenever you fetch or create a new DDO as outlined below. + +### Lowercase service names + +All the service names are now in lowercase: + +old: + +```js +const service = ddo.findServiceByType('Access') +``` + +NEW: + +```js +const service = ddo.findServiceByType('access') +``` + +### Accessing new metadata structure + +Typically you would grab and restructure asset metadata for display. This works the same as before but the key names have changed: + +old: + +```js +const { metadata } = ddo.findServiceByType('Metadata') +const { base, additionalInformation } = metadata +console.log(base.price) +console.log(base.description) +``` + +NEW: + +```js +const { attributes } = ddo.findServiceByType('metadata') +const { main, additionalInformation } = attributes +console.log(main.price) +console.log(additionalInformation.description) +``` + +### `service.serviceDefinitionId` → `service.index` + +old: + +```js +await ocean.assets.order(ddo.id, service.serviceDefinitionId, accounts[0]) +``` + +NEW: + +```js +await ocean.assets.order(ddo.id, service.index, accounts[0]) +``` + +### File attribute changes + +In the file attributes, the `contentLength` is now a string. + +old: + +```json +"files": [ + { + "index": 0, + "url": "https://example-url.net/weather/forecast/madrid/350750305731.xml", + "contentLength": 1000, + "contentType": "text/xml" + } +] +``` + +NEW: + +```json +"files": [ + { + "index": 0, + "url": "https://example-url.net/weather/forecast/madrid/350750305731.xml", + "contentLength": "1000", + "contentType": "text/xml" + } +] +``` diff --git a/README.md b/README.md index abe63a6..a038cd9 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ - [Get started](#get-started) - [Examples](#examples) - [Documentation](#documentation) + - [Migration Guide](#migration-guide) - [Development](#development) - [Testing](#testing) - [Unit Tests](#unit-tests) @@ -75,6 +76,7 @@ For an overview of endpoint configurations making up various Ocean networks, ple You can see how `squid-js` is used on: +- [Docs: React Tutorial](https://docs.oceanprotocol.com/tutorials/react-setup/) - [Integration test](/src/integration/ocean/) - [Tuna](https://github.com/oceanprotocol/tuna/tree/develop/node) @@ -89,6 +91,12 @@ Alternatively, you can generate the raw TypeDoc documentation locally by running npm run doc ``` +### Migration Guide + +Instructions on how to migrate between breaking versions: + +- [Migration Guide](MIGRATION.md) + ## Development To start development you need to: diff --git a/SQUID_INTERFACE.md b/SQUID_INTERFACE.md deleted file mode 100644 index 40abec7..0000000 --- a/SQUID_INTERFACE.md +++ /dev/null @@ -1 +0,0 @@ -this document has been moved to [here](https://github.com/oceanprotocol/dev-ocean/blob/master/doc/architecture/squid.md).