Metadata requests

Metadata requests provide metadata information about the API resources themselves. Information about the current user's permission to use the API resource is also provided, together with information about whether business rules allow changes to be made (even for single fields for PUT requests).

The syntax of the request URI is:

GET https://api.rambase.net/metadata?uri={resourceURL}&verb={resourceVerb}

The response includes the following metadata of the resource:

API resource description
Description of the API resource as found in the documentation.
URI w/parameters
The URI of the API resource, including URL parameters. Each of the URL parameters is presented with the name of the parameter, datatype, description, minimum value, maximum value, etc.
Input fields
All input fields in the API resource. Each field is presented with the name of the field, datatype, xpath, description, minimum value, maximum value etc.
Response fields
All response fields in the API resource. Each field is presented with the name of the field, datatype, path, description and more.
Filter fields
All fields that can be filtered by in the API resource. Each field is presented with the name of the field, datatype, applicable domain values and which macro set to be used.
Sortable fields
All fields that can be sorted by in the API resource. Each field is presented with the name of the field, datatype and description.
Named filters
All named filters that can be used in the filter. Each named filter is presented with the name of the filter and what filter string to use. As with the filter fields, this metadata can be useful when presenting filter opportunities for the users.
Admittance
If the current user for some reason cannot use this API resource, an Admittance tag will be presented, including a message explaining why, an error message identifier and a permission identifier (if permission is missing). If admittance to the API resource is fine, then the same admittance information can be presented for each of the input fields.

Some of the metadata mentioned above is only included if the right $expand query parameter is added:

Description: Include description of the API resource and description of the fields. Ex. $expand=Description
Translated description: Include description of the API resource and translated description of the fields. Remember to add the $lang query parameter to be provided as well. Ex. $expand=TranslatedDescription
Translated name: Include translated name of the fields. Remember to add the $lang query parameter to be provided as well. Ex. $expand=TranslatedName&$lang=nob
Macro definitions: Include information about what the different macro definitions allowed in the filter fields. Ex. $expand=MacroDefinitions
URI parameters: Include URI and metadata for URI parameters. Ex. $expand=URIParameters
Expandable response fields: Include response fields that requires $expand parameter, and what expand parameter to use. Ex. $expand=ExpandableFields

Examples:

In this example we request metadata for the PUT resource of a specified sales order:

GET https://api.rambase.net/metadata?uri=sales/orders/114532&verb=PUT&$expand=Description,UriParameters&$format=json

Here are parts of the response. Note that the response is divided into separate elements for each part of the metadata:

{
    "metadata": {
    "description": "Saves information about the sales order",
    "uri": "sales/orders/{salesOrderId}",
    "uriParameters": [
        {
            "name": "{salesOrderId}",
            "datatype": "Integer",
            "description": "Sales order identifier",
            "isRequired": true,
            "minimumValue": 100000
        }
    ],
    "inputFields": [
        {
            "name": "CustomersReference",
            "datatype": "String",
            "path": "salesOrder.customersReference",
            "description": "Customers reference. Typically a person."
        },
        {
            "name": "CustomersReferenceNumber",
            "datatype": "String",
            "path": "salesOrder.customersReferenceNumber",
            "description": "Customers reference number. E.g. the internal sales order id the customer use in their own system."
        },
        {
            "name": "VolumePriceAgreement",
            "datatype": "String",
            "path": "salesOrder.volumePriceAgreement",
            "description": "Special price agreement related to the quantity beeing ordered. ",
            "applicableDomainValues": "https://api.rambase.net/system/domain-values/applicable-values?object=CUSDOC&field=PRICEAGR",
            "accessDenied": "Cannot update when items exist",
            "accessRuleId": 100208,
            "errorMessageId": 101561
        },
        {
            "name": "Currency",
            "datatype": "String",
            "path": "salesOrder.currency",
            "description": "Three character code following the ISO 4217 standard.",
            "regularExpression": "^[A-Z]{3}$",
            "applicableDomainValues": "https://api.rambase.net/system/domain-values/applicable-values?object=CUS&field=CUR"
        },
        {
            "name": "Note",
            "datatype": "String",
            "path": "salesOrder.note",
            "description": "Additional information regarding the object (free text). This note might be visible to customers/suppliers."
        }
    ],
    "responseFields": [],
    "filterFields": [],
    "sortableFields": [],
    "namedFilters": []
    }
}

In this example we request metadata for the GET resource of listing sales order:

GET https://api.rambase.net/metadata?uri=sales/orders&verb=GET&$expand=Description,MacroDefinitions&$format=json

Here are parts of the response:

{
  "metadata": {
    "description": "List of sales orders",
    "inputFields": [],
    "responseFields": [
      {
        "name": "SalesOrderId",
        "datatype": "Integer",
        "path": "salesOrders.salesOrder.salesOrderId",
        "description": "Sales order identifier",
        "hasDomainDescription": false
      },
      {
        "name": "Status",
        "datatype": "Integer",
        "path": "salesOrders.salesOrder.status",
        "description": "Status of sales order",
        "hasDomainDescription": true
      },
      {
        "name": "Type",
        "datatype": "String",
        "path": "salesOrders.salesOrder.type",
        "description": "Type of sales order. ",
        "hasDomainDescription": true
      },
      {
        "name": "CreatedAt",
        "datatype": "Datetime",
        "path": "salesOrders.salesOrder.createdAt",
        "description": "Date and time of creation",
        "hasDomainDescription": false
      }
    ],
    "filterFields": [
      {
        "name": "AccountManager",
        "datatype": "Integer",
        "description": "Reference to the employee who is responsible for the management of sales, and relationship with the customer.",
        "macroSet": "pid"
      },
      {
        "name": "CreatedAt",
        "datatype": "Datetime",
        "description": "Date and time of creation",
        "macroSet": "datetime"
      },
      {
        "name": "Currency",
        "datatype": "String",
        "description": "Three character code following the ISO 4217 standard.",
        "applicableDomainValues": "https://api.rambase.net/system/domain-values/applicable-values?object=CUS&field=CUR"
      },
      
    ],
    "macroDefinitions": [
      {
        "name": "now",
        "macroSets": "datetime",
        "allowedUnits": "y,M,w,d,h,m,s",
        "defaultUnit": "d"
      },
      {
        "name": "startOfDay",
        "macroSets": "datetime",
        "allowedUnits": "y,M,w,d,h,m,s",
        "defaultUnit": "d"
      },
      {
        "name": "today",
        "macroSets": "date",
        "allowedUnits": "y,M,w,d,h,m,s",
        "defaultUnit": "d"
      },
      {
        "name": "currentUser",
        "macroSets": "pid"
      },
      {
        "name": "currentDB",
        "macroSets": "db"
      }
    ],
    "sortableFields": [
      {
        "name": "AccountManager",
        "datatype": "Integer",
        "description": "Reference to the employee who is responsible for the management of sales, and relationship with the customer."
      },
      {
        "name": "Assignee",
        "datatype": "Integer",
        "description": "The user who has been assigned to work with this object."
      },
      {
        "name": "AssigneeName",
        "datatype": "String",
        "description": "The name of the user who has been assigned to work with this object."
      }
    ],
    "namedFilters": [
      {
        "name": "Active orders",
        "key": "Active",
        "description": "Active sales orders. Sales orders registered, but not delivered yet.",
        "uncombinableWith": []
      },
      {
        "name": "Active or shipped orders",
        "key": "ActiveOrShipped",
        "description": "List of active sales orders and processed orders with one or more items forwarded to shipping advice.",
        "uncombinableWith": []
      },
      {
        "name": "Delayed orders",
        "key": "Delayed",
        "description": "Sales orders that contains item(s) which should have been delivered according to confirmed delivery date.",
        "uncombinableWith": []
      }
    ]
  }
}