Jump to content
Sign in to follow this  
justin nelson

Missing information in Service documentation?

Recommended Posts

Given the information in the following link, how am I supposed to know that this method requires a LogOnRequestDTO in the POST entity body?

http://ciapipreprod.cityindextest9.co.uk/CIAPI.docs/#service.CreateSession

All it tells me is that it has 2 parameters, a username and a password. Does it specify somewhere that I need to form JSON and send it over POST?

Share this post


Link to post
Guest sky.sanders

The jquery sample is the ‘close to the metal’ sample and shows that you are posting json

but yes, you are correct – the docs are not explicit on this.

We are in discussion as to how best to present the information. Your input is welcome.

Share this post


Link to post
Guest sky.sanders

The meta generation stack and docs app have been updated to more accurately reflect input parameters, be they DTO or scalar. The changes will be deployed shortly and this answer will be updated.

Share this post


Link to post

The jquery sample is the ‘close to the metal’ sample and shows that you are posting json

but yes, you are correct – the docs are not explicit on this.

We are in discussion as to how best to present the information. Your input is welcome.

I will spend some time thinking about it. I think we need that information somewhere.

Share this post


Link to post

The jquery sample is the ‘close to the metal’ sample and shows that you are posting json

but yes, you are correct – the docs are not explicit on this.

We are in discussion as to how best to present the information. Your input is welcome.

I think it might be as simple as adding a ‘data’ item to services that need a post entity. See my answer to this question.

Share this post


Link to post

If you’re working with the API directly, then post a LogOnRequestDTO to /session

The documentation shows how you can do it if you are looking at it manually. The issue is when it comes to auto-generating the code. There are no indicators showing what the post body should look like.

Share this post


Link to post
Guest sky.sanders

 

I think we need to add a 'data' property to the Services that require a POST entity. It could look like the following. (Modeled after 'returns'):

"data": {
    "$ref": "#.LogOnRequestDTO"
}

Actually, simply using a $ref as the parameter is the proper solution and will be implemented in the next iteration of the meta generation. If you had been a little bird sitting on our shoulders as the meta stack evolved around an actively developed API the current shortcomings of the meta and doc app would make more sense. David and I have discussed this in the past couple months but the changes needed to the documentation app to support this, as well as the route and dto generation, are significant so it has been somewhat put off. You and I should have a chat and make sure everyone gets what they need while staying as much as possible in the bounds of JsonSchema and SMD.

Share this post


Link to post

 

I think we need to add a 'data' property to the Services that require a POST entity. It could look like the following. (Modeled after 'returns'):

"data": {
    "$ref": "#.LogOnRequestDTO"
}

@sky.sanders That’s great. Where can I find a new copy of the SMD and Schema?

Share this post


Link to post
Guest sky.sanders

 

I think we need to add a 'data' property to the Services that require a POST entity. It could look like the following. (Modeled after 'returns'):

"data": {
    "$ref": "#.LogOnRequestDTO"
}

@justin nelson – in your inbox. consider it an insider’s sneak peek. ;–)

Share this post


Link to post

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
Sign in to follow this  
×