Updated API from documentation release

api-specs/api/types/product/ProductDraft.raml

@@ -23,7 +23,7 @@ properties:
     description: |
       User-defined unique identifier for the Product.
 
-      This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Products with the [Import API](/../import-export/) and the [Merchant Center](/../merchant-center/import-data).
+      This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Products with the [Import API](/../api/import-export/) and the [Merchant Center](/../merchant-center/import-data).
 
       To update a Product using the Import API or Merchant Center, the Product `key` must match the pattern `^[A-Za-z0-9_-]{2,256}$`.
   description?:

api-specs/api/types/product/updates/ProductSetKeyAction.raml

@@ -10,4 +10,4 @@ properties:
     description: |
       Value to set. If empty, any existing value will be removed.
 
-      To update a Product using the [Import API](/../import-export/) and the [Merchant Center](/../merchant-center/import-data), the Product `key` must match the pattern `^[A-Za-z0-9_-]{2,256}$`.
+      To update a Product using the [Import API](/../api/import-export/) and the [Merchant Center](/../merchant-center/import-data), the Product `key` must match the pattern `^[A-Za-z0-9_-]{2,256}$`.

api-specs/connect/types/types.raml

@@ -71,4 +71,3 @@ DeploymentApplicationRequiredError: !include error/DeploymentApplicationRequired
 DeploymentUnknownGlobalConfigurationKeyError: !include error/DeploymentUnknownGlobalConfigurationKeyError.raml
 DeploymentMissingGlobalConfigurationKeyError: !include error/DeploymentMissingGlobalConfigurationKeyError.raml
 DeploymentEmptyRequiredGlobalConfigurationKeyError: !include error/DeploymentEmptyRequiredGlobalConfigurationKeyError.raml
-

api-specs/import/api.raml

@@ -19,7 +19,7 @@ baseUri: https://import.europe-west1.gcp.commercetools.com
       - eastus.azure
       - germanywestcentral.azure
     description: |
-      The [Region](/hosts-and-authorization#hosts) in which the Project is hosted.
+      The [Region](/import-export/hosts-and-authorization#hosts) in which the Project is hosted.
 (annotations.serviceRegions):
   - uri: https://import.us-central1.gcp.commercetools.com/
     region: us-central1
@@ -531,7 +531,7 @@ traits:
         post:
           description: |
             Creates a new import request for Product Variant Patches.
-            Returns an [InvalidField](/error#invalidfielderror) error if the [ProductVariantPatchRequest](ctp:import:type:ProductVariantPatchRequest) contains patches with and without the `product` field set.
+            Returns an [InvalidField](ctp:import:type:InvalidFieldError) error if the [ProductVariantPatchRequest](ctp:import:type:ProductVariantPatchRequest) contains patches with and without the `product` field set.
           is:
             - secured_by_manage_products
           body:

api-specs/import/types/category-import.raml

@@ -10,12 +10,12 @@ uses:
 types:
   CategoryImport:
     description: |
-      The data representation for a Category to be imported that is persisted as a [Category](/../api/projects/categories#category) in the Project.
+      The data representation for a Category to be imported that is persisted as a [Category](ctp:api:type:Category) in the Project.
     type: common.ImportResource
     properties:
       key:
         type: string
-        description: User-defined unique identifier. If a [Category](/../api/projects/categories#category) with this `key` exists, it will be updated with the imported data.
+        description: User-defined unique identifier. If a [Category](ctp:api:type:Category) with this `key` exists, it will be updated with the imported data.
         pattern: ^[A-Za-z0-9_-]+$
         minLength: 2
         maxLength: 256
@@ -35,8 +35,8 @@ types:
       parent?:
         description: |
           Maps to `Category.parent`.
-          The Reference to the parent [Category](/../api/projects/categories#category) with which the Category is associated.
-          If referenced Category does not exist, the `state` of the [ImportOperation](/import-operation#importoperation) will be set to `unresolved` until the necessary Category is created.
+          The Reference to the parent [Category](ctp:api:type:Category) with which the Category is associated.
+          If referenced Category does not exist, the `state` of the [ImportOperation](ctp:import:type:ImportOperation) will be set to `unresolved` until the necessary Category is created.
         type: common.CategoryKeyReference
       orderHint?:
         description: |
@@ -59,6 +59,8 @@ types:
           Maps to `Category.metaKeywords`.
         type: common.LocalizedString
       assets?:
+        description: |
+          Maps to `Category.assets`.
         type: common.Asset[]
       custom?:
         description: The custom fields for this Category.

api-specs/import/types/common.raml

@@ -209,9 +209,14 @@ types:
     properties:
       container: string
   UnresolvedReferences:
+    description: References a resource which could not be resolved.
     properties:
-      key: string
-      typeId: ReferenceType
+      key:
+        type: string
+        description: The `key` of the resource.
+      typeId:
+        type: ReferenceType
+        description: The type of resource.
   MoneyType:
     type: string
     enum:
@@ -245,6 +250,7 @@ types:
     properties:
       value:
         type: TypedMoney
+        description: Money value of the discounted price.
       discount:
         description: Reference to a ProductDiscount.
         type: ProductDiscountKeyReference
@@ -344,7 +350,7 @@ types:
       - key-value-document
   ProcessingState:
     description: |
-      Every [Import Operation](/import-operation) is assigned one of the following states.
+      Every [Import Operation](ctp:import:type:ImportOperation) is assigned one of the following states.
     (annotations.enumDescriptions):
       processing: The initial state assigned if the request payload (JSON structure and fields) meets Import API specifications. The resource import is in progress.
       imported: The resource was successfully imported.

api-specs/import/types/customer-import.raml

@@ -19,47 +19,116 @@ types:
       ExternalAuth: If set, the `password` field is optional for the Customer.
   CustomerAddress:
     description: |
-      Different from Address in that `key` is required and `id` is not supported.
+      Different from [Address](/types#address) in that `key` is required and `id` is not supported.
     properties:
       key:
         description: |
           User-defined identifier for the address.
           Must follow the pattern `[a-zA-Z0-9_\-]{2,256}` and must be unique per customer.
         type: string
-      title?: string
-      salutation?: string
-      firstName?: string
-      lastName?: string
-      streetName?: string
-      streetNumber?: string
-      additionalStreetInfo?: string
-      postalCode?: string
-      city?: string
-      region?: string
-      state?: string
-      country: common.CountryCode
-      company?: string
-      department?: string
-      building?: string
-      apartment?: string
-      pOBox?: string
-      phone?: string
-      mobile?: string
-      email?: string
-      fax?: string
-      additionalAddressInfo?: string
-      externalId?: string
+      country:
+        type: common.CountryCode
+        description: |
+          Name of the country.
+      title?:
+        type: string
+        description: |
+          Title of the contact, for example 'Dr.'
+      salutation?:
+        type: string
+        description: |
+          Salutation of the contact, for example 'Mr.' or 'Ms.'
+      firstName?:
+        type: string
+        description: |
+          Given name (first name) of the contact.
+      lastName?:
+        type: string
+        description: |
+          Family name (last name) of the contact.
+      streetName?:
+        type: string
+        description: |
+          Name of the street.
+      streetNumber?:
+        type: string
+        description: |
+          Street number.
+      additionalStreetInfo?:
+        type: string
+        description: |
+          Further information on the street address.
+      postalCode?:
+        type: string
+        description: |
+          Postal code.
+      city?:
+        type: string
+        description: |
+          Name of the city.
+      region?:
+        type: string
+        description: |
+          Name of the region.
+      state?:
+        type: string
+        description: |
+          Name of the state, for example, Colorado.
+      company?:
+        type: string
+        description: |
+          Name of the company.
+      department?:
+        type: string
+        description: |
+          Name of the department.
+      building?:
+        type: string
+        description: |
+          Number or name of the building.
+      apartment?:
+        type: string
+        description: |
+          Number or name of the apartment.
+      pOBox?:
+        type: string
+        description: |
+          Post office box number.
+      phone?:
+        type: string
+        description: |
+          Phone number of the contact.
+      mobile?:
+        type: string
+        description: |
+          Mobile phone number of the contact.
+      email?:
+        type: string
+        description: |
+          Email address of the contact.
+      fax?:
+        type: string
+        description: |
+          Fax number of the contact.
+      additionalAddressInfo?:
+        type: string
+        description: |
+          Further information on the Address.
+      externalId?:
+        type: string
+        description: |
+          ID for the contact used in an external system.
       custom?:
         description: Custom Fields for the address.
         type: custom-field.Custom
   CustomerImport:
     description: |
-      The data representation for a Customer to be imported that is persisted as a [Customer](/../api/projects/customers#top) in the Project.
+      The data representation for a Customer to be imported that is persisted as a [Customer](ctp:api:type:Customer) in the Project.
     type: common.ImportResource
     properties:
       key:
         type: string
-        description: User-defined unique identifier. If a [Customer](/../api/projects/customers#customer) with this `key` exists, it will be updated with the imported data.
+        description: User-defined unique identifier. If a [Customer](ctp:api:type:Customer) with this `key` exists, it will be updated with the imported data.
         pattern: ^[A-Za-z0-9_-]+$
         minLength: 2
         maxLength: 256
@@ -77,7 +146,7 @@ types:
         type: string
       stores?:
         description: |
-          The References to the Stores with which the Customer is associated. If referenced Stores do not exist, the `state` of the [ImportOperation](/import-operation#importoperation) will be set to `unresolved` until the necessary Stores are created.
+          The References to the Stores with which the Customer is associated. If referenced Stores do not exist, the `state` of the [ImportOperation](ctp:import:type:ImportOperation) will be set to `unresolved` until the necessary Stores are created.
         type: common.StoreKeyReference[]
       firstName?:
         description: |
@@ -121,8 +190,8 @@ types:
         type: boolean
       customerGroup?:
         description: |
-          The Reference to the [CustomerGroup](/../api/projects/customerGroups#customergroup) with which the Customer is associated.
-          If referenced CustomerGroup does not exist, the `state` of the [ImportOperation](/import-operation#importoperation) will be set to `unresolved` until the necessary CustomerGroup is created.
+          The Reference to the [CustomerGroup](ctp:api:type:CustomerGroup) with which the Customer is associated.
+          If referenced CustomerGroup does not exist, the `state` of the [ImportOperation](ctp:import:type:ImportOperation) will be set to `unresolved` until the necessary CustomerGroup is created.
         type: common.CustomerGroupKeyReference
       addresses?:
         description: |

api-specs/import/types/discount-code-import.raml

@@ -32,7 +32,7 @@ types:
         description: |
           User-defined unique identifier of the DiscountCode that is used by the customer to apply the discount.
 
-          The value cannot be updated. Attempting to update the value will result in an [InvalidFieldsUpdate](/error#invalidfieldsupdateerror) error.
+          The value cannot be updated. Attempting to update the value will result in an [InvalidFieldsUpdate](/import-export/error#invalidfieldsupdateerror) error.
         type: string
       cartDiscounts:
         description: |

api-specs/import/types/error.raml

@@ -34,13 +34,17 @@ types:
           The errors that caused this error response.
         type: ErrorObject[]
   ErrorObject:
-    description:
+    description: |
+      Base representation of an error response containing common fields to all errors.
+
+      An error response may contain additional fields depending on the type of an error, for example, `attribute` in [DuplicateAttributeValueError](#duplicateattributevalueerror).
     discriminator: code
     properties:
       code:
+        description: An error identifier.
         type: string
       message:
-        description:
+        description: A plain language description of the cause of an error.
         type: string
   AccessDeniedError:
     description: This is the generic error code for access denied. In case of a wrong scope, an [InvalidScopeError](#invalidscopeerror) will be returned.
@@ -58,15 +62,15 @@ types:
     type: ErrorObject
     discriminatorValue: InvalidOperation
   DuplicateAttributeValueError:
-    description: The `Unique` [AttributeConstraintEnum](/../api/projects/productTypes#attributeconstraintenum) was violated.
+    description: The `Unique` [AttributeConstraintEnum](ctp:api:type:AttributeConstraintEnum) was violated.
     type: ErrorObject
     discriminatorValue: DuplicateAttributeValue
     properties:
       attribute:
         description: The attribute in conflict.
         type: product-variant-import.Attribute
   DuplicateAttributeValuesError:
-    description: The `CombinationUnique` [AttributeConstraintEnum](/../api/projects/productTypes#attributeconstraintenum) was violated.
+    description: The `CombinationUnique` [AttributeConstraintEnum](ctp:api:type:AttributeConstraintEnum) was violated.
     type: ErrorObject
     discriminatorValue: DuplicateAttributeValues
     properties:
@@ -85,8 +89,8 @@ types:
         type: any
   DuplicateVariantValuesError:
     description: |
-      The given combination of values of a [Product Variant](/../api/projects/products#productvariant) conflicts with an existing one.
-      Every [Product Variant](/../api/projects/products#productvariant) must have a distinct combination of SKU, prices, and custom attribute values.
+      The given combination of values of a [Product Variant](ctp:api:type:ProductVariant) conflicts with an existing one.
+      Every [Product Variant](ctp:api:type:ProductVariant) must have a distinct combination of SKU, prices, and custom attribute values.
     type: ErrorObject
     discriminatorValue: DuplicateVariantValues
     properties:
@@ -113,7 +117,7 @@ types:
   InvalidFieldError:
     description: |
       A given field is not supported.
-      This error occurs, for example, if the field `variants`, which is not supported by [Product Import](/product#productimport), is sent to the Product Import endpoint.
+      This error occurs, for example, if the field `variants`, which is not supported by [Product Import](ctp:import:type:ProductImport), is sent to the Product Import endpoint.
     type: ErrorObject
     discriminatorValue: InvalidField
     properties:

api-specs/import/types/import-operation.raml

@@ -17,7 +17,7 @@ types:
         type: integer
         format: long
       importContainerKey:
-        description: The key of the [importContainer](/import-container#importcontainer).
+        description: The key of the [ImportContainer](ctp:import:type:ImportContainer).
         type: string
       resourceKey:
         description: The key of the resource.
@@ -35,7 +35,7 @@ types:
         format: long
       errors?:
         description: |
-          Contains an error if the import of the resource was not successful. See [Errors](/error).
+          Contains an error if the import of the resource was not successful. See [Errors](/import-export/error).
         type: error.ErrorObject[]
       unresolvedReferences?:
         description: |
@@ -98,5 +98,5 @@ types:
       errors?:
         description: |
           The validation errors for the [ImportOperation](#importoperation).
-          See [Errors](/error).
+          See [Errors](/import-export/error).
         type: error.ErrorObject[]