From e2c176b020a65bc6f84252dc4923916b532da752 Mon Sep 17 00:00:00 2001 From: Steve Hall Date: Wed, 26 Jul 2017 18:14:38 +0100 Subject: [PATCH 1/3] Troubleshooting section Updated the README with some error messages that came up during the course of trying this out for the first time on an existing API Platform implementation. Most problems were due to using an incorrect entrypoint to start with and then having authentication on the entrypoint and context routes. Hopefully this will save someone else the time in the future. --- README.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5d85a65a..5661c082 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Reference the Bootstrap CSS stylesheet in `public/index.html` (optional): In the app directory, generate the files for the resource you want: - $ api-platform-generate-crud http://localhost src/ --resource foo + $ api-platform-generate-crud https://demo.api-platform.com/index.jsonld src/ --resource foo # Replace the URL by the entrypoint of your Hydra-enabled API # Omit the resource flag to generate files for all resource types exposed by the API @@ -89,6 +89,34 @@ ReactDom.render( ); ``` +## Troubleshooting +* The generator does not perform any authentication, so you must ensure that all referenced hydra paths for your API are accessible anonymously. If you are using [API Platform](https://api-platform.com) this will at least include: +``` +api_entrypoint ANY ANY ANY /{index}.{_format} +api_doc ANY ANY ANY /docs.{_format} +api_jsonld_context ANY ANY ANY /contexts/{shortName}.{_format} +``` + +* If you recieve `Error: The class http://www.w3.org/ns/hydra/core#ApiDocumentation doesn't exist.` you may have specified the documentation URL instead of the entrypoint. For example if you are using [API Platform](https://api-platform.com) and your documentation URL is at https://demo.api-platform.com/docs the entry point is likely at https://demo.api-platform.com/index.jsonld. + +* If you receive `TypeError: Cannot read property '@type' of undefined` or `TypeError: Cannot read property '0' of undefined` check that the URL you specified is accessible and returns jsonld. You can check from the command line you are using by running something like `curl https://demo.api-platform.com/`. + +* If you receive a message like this: +``` +{ Error + at done (/usr/local/share/.config/yarn/global/node_modules/jsonld/js/jsonld.js:6851:19) + at + at process._tickCallback (internal/process/next_tick.js:188:7) + name: 'jsonld.InvalidUrl', + message: 'Dereferencing a URL did not result in a JSON object. The response was valid JSON, but it was not a JSON object.', + details: + { code: 'invalid remote context', + url: 'https://demo.api-platform.com/contexts/Entrypoint', + cause: null } } +``` + +Check access to the specified url, in this case `https://demo.api-platform.com/contexts/Entrypoint`, use curl to check access and the response `curl https://demo.api-platform.com/contexts/Entrypoint`. In the above case an "Access Denied" message in JSON format was being returned. + ## TODO * Add support for pagination From 3edac4fafc5b63ed1f9e51398bf8da3ddd3559c8 Mon Sep 17 00:00:00 2001 From: Steve Hall Date: Mon, 14 Aug 2017 16:43:55 +0100 Subject: [PATCH 2/3] Move troubleshooting to its own file so as not to overload the main README. --- README.md | 32 ++------------------------------ Troubleshooting.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 30 insertions(+), 30 deletions(-) create mode 100644 Troubleshooting.md diff --git a/README.md b/README.md index 5661c082..be25d410 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Reference the Bootstrap CSS stylesheet in `public/index.html` (optional): In the app directory, generate the files for the resource you want: - $ api-platform-generate-crud https://demo.api-platform.com/index.jsonld src/ --resource foo + $ api-platform-generate-crud https://demo.api-platform.com src/ --resource foo # Replace the URL by the entrypoint of your Hydra-enabled API # Omit the resource flag to generate files for all resource types exposed by the API @@ -89,34 +89,6 @@ ReactDom.render( ); ``` -## Troubleshooting -* The generator does not perform any authentication, so you must ensure that all referenced hydra paths for your API are accessible anonymously. If you are using [API Platform](https://api-platform.com) this will at least include: -``` -api_entrypoint ANY ANY ANY /{index}.{_format} -api_doc ANY ANY ANY /docs.{_format} -api_jsonld_context ANY ANY ANY /contexts/{shortName}.{_format} -``` - -* If you recieve `Error: The class http://www.w3.org/ns/hydra/core#ApiDocumentation doesn't exist.` you may have specified the documentation URL instead of the entrypoint. For example if you are using [API Platform](https://api-platform.com) and your documentation URL is at https://demo.api-platform.com/docs the entry point is likely at https://demo.api-platform.com/index.jsonld. - -* If you receive `TypeError: Cannot read property '@type' of undefined` or `TypeError: Cannot read property '0' of undefined` check that the URL you specified is accessible and returns jsonld. You can check from the command line you are using by running something like `curl https://demo.api-platform.com/`. - -* If you receive a message like this: -``` -{ Error - at done (/usr/local/share/.config/yarn/global/node_modules/jsonld/js/jsonld.js:6851:19) - at - at process._tickCallback (internal/process/next_tick.js:188:7) - name: 'jsonld.InvalidUrl', - message: 'Dereferencing a URL did not result in a JSON object. The response was valid JSON, but it was not a JSON object.', - details: - { code: 'invalid remote context', - url: 'https://demo.api-platform.com/contexts/Entrypoint', - cause: null } } -``` - -Check access to the specified url, in this case `https://demo.api-platform.com/contexts/Entrypoint`, use curl to check access and the response `curl https://demo.api-platform.com/contexts/Entrypoint`. In the above case an "Access Denied" message in JSON format was being returned. - ## TODO * Add support for pagination @@ -131,4 +103,4 @@ Check access to the specified url, in this case `https://demo.api-platform.com/c ## Credits -Created by [Kévin Dunglas](https://dunglas.fr). Sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop). +Created by [Kévin Dunglas](https://dunglas.fr). Sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop). \ No newline at end of file diff --git a/Troubleshooting.md b/Troubleshooting.md new file mode 100644 index 00000000..5cb1b0bd --- /dev/null +++ b/Troubleshooting.md @@ -0,0 +1,28 @@ + +# Troubleshooting +* The generator does not perform any authentication, so you must ensure that all referenced hydra paths for your API are accessible anonymously. If you are using [API Platform](https://api-platform.com) this will at least include: +``` +api_entrypoint ANY ANY ANY /{index}.{_format} +api_doc ANY ANY ANY /docs.{_format} +api_jsonld_context ANY ANY ANY /contexts/{shortName}.{_format} +``` + +* If you recieve `Error: The class http://www.w3.org/ns/hydra/core#ApiDocumentation doesn't exist.` you may have specified the documentation URL instead of the entrypoint. For example if you are using [API Platform](https://api-platform.com) and your documentation URL is at [https://demo.api-platform.com/docs] the entry point is likely at [https://demo.api-platform.com]. You can see an example of the expected response from an entrypoint in your browser by clicking visiting [https://demo.api-platform.com/index.jsonld]. + +* If you receive `TypeError: Cannot read property '@type' of undefined` or `TypeError: Cannot read property '0' of undefined` check that the URL you specified is accessible and returns jsonld. You can check from the command line you are using by running something like `curl https://demo.api-platform.com/`. + +* If you receive a message like this: +``` +{ Error + at done (/usr/local/share/.config/yarn/global/node_modules/jsonld/js/jsonld.js:6851:19) + at + at process._tickCallback (internal/process/next_tick.js:188:7) + name: 'jsonld.InvalidUrl', + message: 'Dereferencing a URL did not result in a JSON object. The response was valid JSON, but it was not a JSON object.', + details: + { code: 'invalid remote context', + url: 'https://demo.api-platform.com/contexts/Entrypoint', + cause: null } } +``` + +Check access to the specified url, in this case `https://demo.api-platform.com/contexts/Entrypoint`, use curl to check access and the response `curl https://demo.api-platform.com/contexts/Entrypoint`. In the above case an "Access Denied" message in JSON format was being returned. \ No newline at end of file From aa9681f6593029c8eeea6bdbb21cefb6ea6d35e2 Mon Sep 17 00:00:00 2001 From: Steve Hall Date: Mon, 14 Aug 2017 16:47:46 +0100 Subject: [PATCH 3/3] Replace newline at end of file. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index be25d410..ef0b685b 100644 --- a/README.md +++ b/README.md @@ -103,4 +103,4 @@ ReactDom.render( ## Credits -Created by [Kévin Dunglas](https://dunglas.fr). Sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop). \ No newline at end of file +Created by [Kévin Dunglas](https://dunglas.fr). Sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop).