Output Entity Definitions

Most end points you write will provide some type of output back to the user. The metadata around output entity definitions is very similar to input entity definitions. Output entity definitions are flat structures that cannot contain complex types like other objects. The framework always takes the last piece output returned by the business logic of the end point and maps it into your output entity definition. This is a core feature of the framework. Mapping business logic output to output entity objects is handled by implementations of Endpoints.IOutputMapper. Out of the box, we support mapping DataTables and GEs into the output for an endpoint.

The output entity definition can have the following properties:

Output Entity Definition properties

TODO double check the input entity definition fields against the interface.

Property Name	Value	Description
Name	string	A unique identifier for this output entity definition. The identifier must be unique within the entire Endpoint.json definition file.
Description	string	A description for this payload that will be surfaced in the public API documentation.
IsCollection	bool	Indicates whether or not the output of this payload is a collection of objects or a single object.
Fields	object	Within the value object each property name is the expected output field name. That property's value is a Field Object (described below).

Field Object properties

The field's property on the output entity definition should be an object value. Each property on the object should be the expected output field name. That property's value should be an object with the following properties:

Property Name	Value	Description
Type	string	Describes what type the framework should expect for the output field. Valid types are string, int, integer, long, decimal, bool, boolean, date, datetime, array and double.
Description	string	A description for this field that will be surfaced in the public API documentation.
SourceField	string	If the output payload is a GE, this value allows you to automatically map public facing fields to backend fields.

And end point does not need an output entity definition. In these cases as long as there are no errors executing the request the response will be HTTP 204 status code.

Examples

Assume we want to define the output for a route GET /examples/products/{productId}. The metadata could look like this:

{
  "endpoints": {             
    "ExamplesGetSingleProduct": {
      "outputEntityDefinition": {
        "name": "ExampleProductOutput",
        "fields": {
          "id": {
            "type": "long"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "A plain text description of the product."
          },
          "hasComplexPricing": {
            "type": "boolean",
            "description": "If true, this indicates you must add the product to the cart in order to get an accurate price."
          },
          "defaultPrice": {
            "type": "decimal"
          }    
      }
      //remaining metadata omitted
    }
  }
}

If our endpoint was to get a collection of products, such as GET /examples/products/, we could define the output this way instead:

{
  "endpoints": {             
    "ExamplesAllProducts": {
      "outputEntityDefinition": {
        "name": "ExampleAllProductsOutput",
        "isCollection" : true,
        "fields": {
          "id": {
            "type": "long"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "description": "A plain text description of the product."
          },
          "hasComplexPricing": {
            "type": "boolean",
            "description": "If true, this indicates you must add the product to the cart in order to get an accurate price."
          },
          "defaultPrice": {
            "type": "decimal"
          }    
      }
      //remaining metadata omitted
    }
  }
}

Often you will want to define a collection based endpoint like GET /examples/products and a singular resource endpoint like GET /examples/products/{productId}. It is possible to avoid duplicating most of the output entity definition metadata using references.

6.0 Product Knowledge

If you have a comment on this topic, contact Aptify Documentation. If you want to return to the Aptify Community Site, please click here.

Output Entity Definitions

Examples