Missing information in Service documentation?

[justin nelson 15]

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?

[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.

[timothy 0]

The docs have been updated to include links to the data types you need 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.

[timothy 0]

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

[justin nelson 15]

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 15]

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.

[justin nelson 15]

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.

[justin nelson 15]

The docs have been updated to include links to the data types you need to post.

Great, thanks. Do you know where I can find a copy of the latest SMD and Schema?

[justin nelson 15]

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.

[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.

[justin nelson 15]

 

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?

[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. ;–)