Hello guys,
I’m facing a problem, when I try to import the swagger specs (https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/streaming.json) to my OutSystems Applications and this operation fails, giving the error:
.“Invalid REST API
StreamingAPI must have at least one method.”
Can you please help?
Best regards,
try importing this (for companies)
https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/stream.json#/companies
Unfortunately this looks like the same issue as the main REST API specs have e.g. they’ve been put up in a form where a local host and port has been specified rather than the external host name. So all over the json you’ll see links of the form:
“http://127.0.0.1:31917/api.ch.gov.uk-specifications/swagger-2.0/spec/…”
It’s simple to correct though I believe, just substitute:
"http://127.0.0.1:31917/"
for
"https://developer-specs.company-information.service.gov.uk/"
(I think you can use http but https should be fine)
This applies to the companies link above also.
Chris
Hi,
Yes, you’re right. The Swagger file was some problems.
But even, replacing the localhost address with the “https://developer-specs.company-information.service.gov.uk/”, I still can’t import the WebService, it gives me the same error. “…must have at least one method”…
Chris, do you have any other idea?
Best regards,
Steven
Hi Phillip,
Importing for the companies gives me the error “The Swagger file doesn’t have a version specified or the version is incorrect.”.
But with the feedback from “voracityemail” I notice that insite this swagger file there are still some problem with the localhost links (“http://127.0.0.1:31844/api.ch.gov.uk-specifications/swagger-2.0/models/stream/companyProfile.json#/definitions/companyProfileStream”)
I saved a local file and replace the localhost (http://127.0.0.1:31844) to (https://developer-specs.company-information.service.gov.uk/) and it still gives me the same error.
Thanks,
Steven
I don’t know exactly why you’re getting a particular error in your tool. I guess the “missing method” means that it couldn’t find the following:
(top level)
paths.(some path e.g. /companies).get (or post etc.)
If you don’t start from the main file that’s probably why it complains about missing or incorrect version - because that’s where that’s defined.
In my (limited) experience working with json schemas and in particular Swagger / OpenAPI always involves some effort. I don’t think we’ve seen one where someone published a schema and it would just work as it was. That might also be down to the tool you’re using / where you’re trying to import it to however.
You will probably need to start from the main document (otherwise you’ll be missing information like version):
https://developer-specs.company-information.service.gov.uk/api.ch.gov.uk-specifications/swagger-2.0/spec/streaming.json
The “$ref” JSON pointer is used frequently in the CH schema. That means files can reference other files, which in turn can reference other files, files can reference themselves (either “internally” using “#” or with a host / path prefix) etc. So you’d have to ensure that all such references to e.g. "http://127.0.0.1:31917/" work. That means if you create a local copy of one file with correct refs, the files it pulls in will still have incorrect refs, and when corrected those in turn will likely reference another file with the same issue etc.)
There are different ways you can fix this. However as a quick test I was able to get one end-point to “work” (see below). I did that by manually including the appropriate details in definitions and correcting the refs to point there (internally).
So if there is a referenced file at:
http://something/path/spec.json#/definitions/blah
…which contains
{ "definitions": { contents here } }
… you can add the contents to the main file’s definitions (create one at the top level if not there).
The reference should be changed to:
#/definitions/blah
…and you’ll need to do the same with everything in the contents.
However even then I found issues - which your tool may or may not complain about:
Repetition / redefinition of the parameters member in the paths section e.g. paths./companies.get.parameters
Read only properties marked as “required”
Semantic error at definitions.streamEnvelope.required.0
Read only properties cannot be marked as required by a schema.
There are various ways you could resolve all this. For info you could try putting stuff into Swagger’s (well, SmartBear’s) own interactive editor / validator at:
https://editor.swagger.io/
They have a parser / validator too at:
I’m sure you can make this work. It’s hacky but in my experience this is not unusual! Good luck.
In that case, you’ll need to download ALL the files referenced and fix the references to point to the local files in each file (starting at the very top). That should fix it.
Where can you download all these files? Not sure I understand why they would publish their OAS documentation without proper reference links?
The files/schemas are “incorrectly” referenced within the json - you simply need to replace the domain:port (mine was 127.0.0.1:31871/) portion with developer-specs.company-information.service.gov.uk
PS: once you download the first schema, it is a simple case of replacing that and when you import it’ll correctly resolve.
Thanks for the quick response @phillip ! Although, I might still be confused since I still can’t seem to get it working. Here are my steps:
Is the expectation to go through each and every reference link manually and do a “find and replace” or am I missing something obvious here that will allow me to it all in 1 action?
Thanks again for your support!
Yes, that’s the issue here! linked json files may also have reference links that are “broken”.
You’ll have to download all the referenced files locally AND will also have to edit each reference to remove the port (not the domain as they’d now be hosted locally).
Wow ok! I was afraid you would say that. There are roughly ~30 reference links on the main JSON. If each one has an additional 3-4 reference links, that’s roughly ~100 JSON files we would need to download and update, manually and 1 at a time.
Does that sound about right? Is there really no way to obtain all the files at once?
Thanks again for all your quick support! This is really helpful. I was pulling my hair out trying to figure this out!
This is NOT support! I am simply a user sharing my experience dealing with the CH API.
But yes, looks like you’d need to do exactly as you say. As for there being a better way to download the files, I know not of another (but may be I haven’t looked in all the right places). Saying that, CH staff have visibility on this and they can advise as appropriate.
got it, understood. If you ever figure out a way to obtain the files, please reply back here!
Welcome. Sure will if I ever find a way
PS: by the way, and I am sure you are aware, you can always make those references file references rather than URL references when you save them to disk.
I managed to get a complete API spec with correct references, by writing a little script that gets the entrypoint url and then resolves all JSON references, while I run a simple proxy server on localhost that redirects to developer-specs.company-information.service.gov.uk. I ended up with a single large API spec file. I know it sounds a bit ridiculous to do all this, but it worked for me.
Unfortunately I found that the response formats in the API spec do not always match the actual response formats of the API and there are inconsistencies and spelling mistakes in the API spec. Don’t rely on it as being perfect.
Wow that’s great to hear @ebrian101 . Do you mind sharing that API spec file? I’ll take it with a grain of salt considering the errors you mention. If you are willing to share, feel free to email me at: nolandsmith1@gmail.com
Thanks again! CH should really be providing simple ways to access the full API spec files. Would be a great suggestion to provide.
Sorry for a slow reply, but see this issue is getting comments elsewhere.
For the spec file that I produced please see https://github.com/mrbrianevans/companies-db/tree/master/spec on github, but bear in mind that its now 2 years old, so may be better off running the script.
If you clone the repo (or just copy/paste the file contents of the javascript scrips), you can run https://github.com/mrbrianevans/companies-db/blob/master/spec/parseSpec.js with nodejs (after installing dependencies with npm) to generate a consolidated API spec file.
As mentioned in my original answer, there is a proxy set up on localhost to point to companies house to resolve the specs: https://github.com/mrbrianevans/companies-db/blob/master/spec/proxy-ch.js
Hope thats of use.
