search

hmrc / agent-client-authorisation

Apache License 2.0
4 stars 4 forks source link

RAML Url #90

Open andyws opened 7 years ago

andyws commented 7 years ago

What is the RAML Url for the beta api?

Do you use the RAML to auto-generate client/server code/documentation?

andyws commented 7 years ago

As a follow-up I have loaded a local copy of the application raml into apiworkbench. I get the following errors:


Can not resolve http://api-documentation-raml-frontend.service/api-documentation/assets/common/docs/versioning.mdat line 13 col 4
Error
Can not resolve http://api-documentation-raml-frontend.service/api-documentation/assets/common/docs/errors.mdat line 15 col 4
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/securitySchemes.raml'at line 18 col 3
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/headers.raml'at line 19 col 3
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/annotations.raml'at line 20 col 3
Error
Can not resolve library from path: 'http://api-documentation-raml-frontend.service/api-documentation/assets/common/modules/types.raml'at line 21 col 3

I wish to use the raml to auto-generate client and test stubs. how would you suggest I proceed?

andyws commented 7 years ago

I feel that even though this is a fairly simple api there is a total lack of context contained in the documentation. By ‘context’ I mean items such as:

  1. Narrative explaining how the api is to be exercised, ie the various scenarios/use cases which the api is supposed to satisfy.

  2. Interaction diagrams which underpin the above in a more systematic way.

frankoid commented 7 years ago

Hi,

At the moment the RAML is only used internally, for example the documentation you can view is generated from it.

Since it is internal there is no public URL and it contains references to other internal URLs which is why those links can't be resolved and you can't easily use it to auto-generate client and test stubs.

We may publish RAML in the future, Alex Browne (API Platform Product Manager) is probably a good person to ask about that.

andyws commented 7 years ago

My experience with the creation and implementation of APIs leads me to expect that development should be led by using a spec ( RAML / Swagger ). This should include not just the implementation team but also the consumers of an API.

frankoid commented 7 years ago

I've let the API Platform team know about this github issue because whether we publish RAML is likely to be decided on a platform-wide basis.

andyws commented 7 years ago

Ok. Out of curiosity do any of your team see it as unusual to do API development whereby a spec ( RAML / Swagger ) is used to unambiguously communicate an api and allow the automatic and thereby less defect prone generation of boilerplate code on both the client and server?