= Simplified Representations (v2 Draft)

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Simplified profile `urn:org.apache.isis/v2`

== Draft

=== Response Contract

.Representation Types (Content-Type header attribute 'repr-type')
[cols="1,3,2a", options="header"]
|===

| Type
| Description
| Http Return Code

| object
| when a domain object is rendered
| - 404: when _null_
- 200: otherwise


| object-collection
| when a parented collection is rendered
| - 404: when _null_ or empty
- 200: otherwise

| list    
| when a standalone collection is rendered
| - 404: when _null_ or empty
- 200: otherwise

| value
| when a single value is rendered
| - 404: when _null_
- 200: otherwise 

| values
| when a list of (nullable) values is rendered
| - 404: when _null_ or empty
- 200: otherwise  

| void    
| when a void action result is rendered
| 200

|===

=== Scalar Value DTO

A generic scalar value wrapper, that supports representation of null references as required for
rendering lists of values (`repr-type=values`).

.ScalarValueDtoV2
[source,java]
----
@Data
class ScalarValueDtoV2 {
   
   private String type;
   private Object value;
   
}
----
    
=== Conversation Examples

.Autogenerated by RestServiceSimpifiedRepresentationTest
[cols="a,a", options="header"]
|===
|Action |Request and Response 

|[source,java]
----
@Action
void voidResult() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VOID

[source,json]
----
[]
----


|[source,java]
----
@Action
String string() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VALUE

[source,json]
----
{"type":"String","value":"aString"}
----


|[source,java]
----
@Action
String stringNull() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
String[] stringArray() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VALUES

[source,json]
----
[{"type":"String","value":"Hello"},{"type":"String","value":"World!"}]
----


|[source,java]
----
@Action
String[] stringArrayEmpty() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
String[] stringArrayNull() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
List<String> stringList() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VALUES

[source,json]
----
[{"type":"String","value":"Hello"},{"type":"String","value":"World!"}]
----


|[source,java]
----
@Action
List<String> stringListEmpty() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
List<String> stringListNull() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
Integer integer() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VALUE

[source,json]
----
{"type":"Integer","value":123}
----


|[source,java]
----
@Action
Integer integerNull() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
int integerPrimitive() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VALUE

[source,json]
----
{"type":"Integer","value":123}
----


|[source,java]
----
@Action
BigInteger bigInteger() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VALUE

[source,json]
----
{"type":"BigInteger","value":18446744073709551614}
----


|[source,java]
----
@Action
BigInteger bigIntegerNull() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
List<BigInteger> bigIntegerList() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: VALUES

[source,json]
----
[{"type":"BigInteger","value":0},{"type":"BigInteger","value":18446744073709551614}]
----


|[source,java]
----
@Action
Customer customer() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: OBJECT

[source,json]
----
{"age":22,"name":"Hello World!"}
----


|[source,java]
----
@Action
Customer customerNull() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
List<Customer> customerList() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: LIST

[source,json]
----
[{"age":22,"name":"Alice"},{"age":33,"name":"Bob"}]
----


|[source,java]
----
@Action
List<Customer> customerListEmpty() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
List<Customer> customerListNull() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 404
- Representation Type: null

[source,json]
----
----


|[source,java]
----
@Action
List<BigComplex> complexList() {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{

}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: LIST

[source,json]
----
[{"im":"0","re":"0"},{"im":"-4.3","re":"2.1"}]
----


|[source,java]
----
@Action
BigComplex complexAdd(
    String are, 
    String aim, 
    String bre, 
    String bim) {
    /*...*/
}
----

|==== REQUEST

[source,json]
----
{
   "are": {"value" : "1.0000000000000000000000000000000000000001"},
   "aim": {"value" : "-2.0000000000000000000000000000000000000002"},
   "bre": {"value" : "3"},
   "bim": {"value" : "4"}
}
----

==== RESPONSE

- HTTP return code: 200
- Representation Type: OBJECT

[source,json]
----
{"im":"1.9999999999999999999999999999999999999998","re":"4.0000000000000000000000000000000000000001"}
----

|===
