JSON REST API Documentation

JSON REST API Documentation

  

Hello Devs,


I'm creating a series of API endpoints for my service to expose. I want to create an endpoint which can accept a JSON string which is a list of records of a particular datatype. I can do this if I create a JSON input parameter for the API method but the JSON input parameter must be of type text instead of type list of records of datatype. 

This is fine but when I get outsystems to create the documentation of the API, the documentation only shows that the input parameter is of type text, it gives no indication of how to structure the JSON text for the method to properly consume. 

To say this another way to try to make it clear, if I create a JSON input parameter in a REST interface method, the documentation just reads that the JSON parameter bust have text sent to it. It doesn't say what structure the text should be in to match the JSON expected by the method. 

Does anyone know if I might be doing something wrong or a way of getting the documentation to list the structure of the JSON?

Thanks!

Solution

Hi Rivan,

I suggest you first read OutSystens documentation on how to expose a rest API.

https://success.outsystems.com/Documentation/10/Extensibility_and_Integration/REST/Expose_REST_APIs

To expose a list of records as a JSON, you need to define the parameter as a list of record. OutSystems will translate it to a valid JSON structure.

You can easily test the result of your exposed API by using for example Postman tool.

Regards,

Daniel

Solution

Hi Daniel,

Thanks for the links, I have indeed read through that documentation and am doing my testing in Postman. 

However my question still remains, I've attached a screenshot to explain. The two CreateorUpdateJob endpoints take in the same data, but one has inputs separately defined and another has the data come in via JSON which allows for multiple records to be created or updated with one call. 

However the JSON endpoint doesn't document the structure of the JSON whereas the top endpoint does which makes it much easier for developers. 

Do you know how I might be able to define a JSON input but also specify the structure that the JSON needs to be in?

Thanks,

Ruvan 

Hi Daniel,

I'm sorry I haven't been able to communicate the problem well enough yet, I'll try with more pictures :)

In one of the pages you linked me to, you can see that the documentation outputs the structure of the JSON and the content type is set to 'application / json' - see picture below

But my documentation comes out as below, see black circle showing JSON input just as a string, not the required structure of the JSON.


Also for a standard GET method which outputs a list in JSON format, still my documentation just says that the method will output text rather than give the structure of the output.


Based on the first picture in this post, taken from one of the pages you linked me to, it looks like OutSystems should be able to show the structure but I can't work out how to make it show. 

Any guidance would be welcomed. 

Thanks,

Ruvan

Hi Ruvan,

I think you don't quite understand how the Platform works with REST and JSON. It seems you want to feed JSON to a Text Attribute, and you are surprised the Platform doesn't know what you feed it? You say "another has the data come in via JSON which allows for multiple records to be created or updated with one call" - but that's just not how the Platform works. If you want multiple records to be sent, you need to use a List, and have that as input for the REST service.

Hi Kilian,

Ah, okay you are right, I didn't understand how OutSystems wanted me to set the data type of the input parameter. I had the input parameter set to 'text' and used the JSONDeserialiser to pull apart the text to get individual records.

But if I just set the input parameter as a list of records of job data types, then the documentation shows the correct structure as can be seen in the image below. 


Thank you both of you for your help!

Hi Ruvan,

Thanks for the feedback, glad you got it solved. In general, there should never be a reason to assign JSON to an Attribute, instead of defining the right Structure and use that.