Document all query params in the shipping guide

#%RAML 0.8
---
title: Shipping Guide API
baseUri: https://api.bring.com/shippingguide/products

documentation:
- title: Introduction
  content: |
      The Shipping Guide (Fraktguiden) is a free service from Bring that provides

      * price information,
      * service area (norwegian: dekningsområde), and
      * estimated delivery times.

      With the Shipping Guide it is easy to offer different shipping alternatives to your end customers. Whether they want to

      * get delivery to the door (daytime or evening),
      * pick up the shipment at a post office, or
      * get the shipment delivered to the mailbox

      The Shipping Guide returns the recommended way to present these shipping alternatives, as well as prices and delivery times.

      [Demo shipping alternatives](http://fraktguide.bring.no/fraktguide/demoVelgFraktalternativ.do?from=0484&to=0470&weightInGrams=800&length=10&width=20&height=5&product=servicepakke&product=pa_doren&product=bpakke_dor-dor&product=smaapakker_a-post&product=ekspress09&product=smaapakker_b-post&product=courier_1h&product=minipakke&callbackUrl=http://fraktguide.bring.no/fraktguide/popupCallback.jsp&date=2015-10-07) form (Norwegian).

      The demo shows that the Shipping Guide returns product categories for each request, making a shipping alternatives-page easy to set up. The focus is on delivery methods to the end customer, not product names.

      The Shipping Guide has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality. There are some limitations in the XML/JSON API, such as the inability to mark a parcel as a specialized goods.

      There is also a [Offline SOAP service](http://developer.bring.com/additionalresources/offlinedata.html?from=shipping) for retrieving data for offline use (get complete prices, service area and delivery times based on a fixed sender postal code).

- title: Guidelines
  content: |
      `<MainDisplayCategory>` should be written in bold text and followed by our logo. [Get approved logo here](http://mediaweb.posten.no/fotoweb/Default.fwx?archiveId=5005).

      In the webshop you should display

      * `<MainDisplayCategory>`
      * `<DisplayName>`
      * `<DescriptionText>`

      Repeat the last two as needed, depending on the number of options you would like to display.

      The following values are not meant for display in the webshop and as such should not be visible on your site

      * `<Product>`
      * `<ProductId>`
      * `<ProductCodeInProductionSystem>`

      *We strongly advise that you give your customers at least two options, home delivery and pickup point.*

      | XML | JSON/JSONP | Web services/SOAP |
      |:----|:-----------|:------------------|
      | The XML API is an easy way to integrate with the Shipping Guide using plain HTTP clients. It is also the best API to use when exploring the service using a web browser. | Web browsers can (using JavaScript) retrieve information from external sites if the data are made available in JSONP format. The purpose is that you can paste HTML / Javascript on your web page and easily use data from the Shipping Guide without server components on your web page. See widgets. | The SOAP API has the complete feature set of the Shipping Guide. It requires a SOAP client and the use of our WSDL. It has an Online version (one request per shipment) or an offline version (e.g. nightly fetch prices, service area and delivery times based on a fixed consignor postal code). |

/price{mediaTypeExtension}:
  displayName: Get shipment prices
  securedBy: [mybring_headers, null]
  description: |
      TODO: description
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get shipment prices
    queryParameters:
      from:
        displayName: From postal code
        type: string
        example: 7600
      to:
        displayName: To postal code
        type: string
        example: 1407
      weightInGrams:
        displayName: Weight of package in grams
        type: integer
        example: 1500
      width:
        displayName: Package width in centimeters
        type: integer
        example: 40
      length:
        displayName: Package length in centimeters
        type: integer
        example: 40
      height:
        displayName: Package height in centimeters
        type: integer
        example: 30
      date:
        displayName: Shipping date
        description: Specifies which date the parcel will be delivered to Bring (within the time limit), and is used to calculate the delivery date. Date is specified in ISO format, `YYYY-MM-DD`.
        type: date
        example: 2015-11-18
      time:
        displayName: Shipping time
        description: Shipping time may be specified. Note that Bring's courier products are the only one affected by this parameter. Time is specified in ISO format, `HH:mm`.
        type: date
        example: 12:30
      clientUrl:
        displayName: Client URL
        description: To use the Shipping Guide you must specify a client url parameter. The client url should be set to the url of the web shop or application the end user is ordering from. The client url can be sent as a url parameter, clientUrl, or as a header, `X-Bring-Client-URL`.
        type: string
        example: https://www.example.com/amazing-clothes/
      edi:
        displayName: EDI setting
        description: Flag that tells if the parcel will be registred using EDI when it is shipped. Note that this flag may affect price and which products are available.
        type: boolean
        default: true
      postingAtPostOffice:
        description: |
          Flag that tells whether the parcel is delivered at a post office when it is shipped.

          A surcharge will be applied for the following products:

          * SERVICEPAKKE
          * BPAKKE_DOR-DOR (Bedriftspakke)
        type: boolean
        default: false
      additional:
        displayName: Additional services
        description: Request additional services for the package. Specified by adding one or more `additional` parameters to the request, e.g. [&additional=postoppkrav&additional=evarsling](https://api.bring.com/shippingguide/products/SERVICEPAKKE/price.json?clientUrl=insertYourClientUrlHere&from=7600&to=1407&weightInGrams=1500&date=2009-3-27&additional=postoppkrav&additional=evarsling&additional=lordagsutkjoring). See the [additional services list](/api/product-list/#additional-services). The Shipping Guide will match the additional service codes to the requested products and ignore product / additional service codes that are not applicable.
        type: string
        example: evarsling
      priceAdjustments:
        displayName: Price adjustments
        description: Option to adjust the price returned. Specified by adding [&priceAdjustment=m20p](https://api.bring.com/shippingguide/products/SERVICEPAKKE/price.json?clientUrl=insertYourClientUrlHere&from=7600&to=1407&weightInGrams=1500&priceAdjustment=m20p). Note that price adjustments is on prices without VAT. Refer to additional examples to read more.
        type: string
        example: m20p
      pid:
        displayName: Public ID
        description: The last part (after the last dash) of your identification string (logged-in information for user of Shipping Guide). This makes the Shipping Guide know who performs the query, so we may contact the correct shipping guide user for potential follow ups.
        type: string
      product:
        displayName: Products
        description: This parameter lets you specify which products you want to return information about. If you omit this parameter, you get the default product list (not recommended for production usage). Product is specified by adding one or more product parameters, e.g. [product=servicepakke&product=bpakke_dor-dor](https://api.bring.com/shippingguide/products/price.json?clientUrl=insertYourClientUrlHere&from=7600&to=1407&weightInGrams=1500&product=servicepakke&product=bpakke_dor-dor).
        type: string
        example: bpakke_dor-dor
      language:
        displayName: Language
        description: Which language the descriptive product texts should have. Supported languages are English (en), Swedish (se), Finnish (fi), Danish (da) and Norwegian (no). If no language is set, or text is not available in the requested language, norwegian text is returned.
        type: string
        default: no
        example: en
      volumeSpecial:
        displayName: Special volume
        description: Flag to indicate if the package has a shape that may require 'special handling fee'. [product=servicepakke&product=bpakke_dor-dor](https://api.bring.com/shippingguide/products/price.json?clientUrl=insertYourClientUrlHere&from=7600&to=1407&weightInGrams=1500&product=servicepakke&product=bpakke_dor-dor&volumeSpecial=true).
        type: boolean
        default: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
          application/xml:

/expectedDelivery{mediaTypeExtension}:
  displayName: Get estimated delivery time
  securedBy: [mybring_headers, null]
  description: |
      TODO: description
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get estimated delivery time
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
          application/xml:

/all{mediaTypeExtension}:
  displayName: Get shipment prices, estimated delivery and more
  securedBy: [mybring_headers, null]
  description: |
      TODO: description
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get shipment prices, estimated delivery and more
    queryParameters:
      q:
        description: Get shipment prices, estimated delivery time and additional information
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
          application/xml:

#%RAML 0.8
---
title: Shipping Guide API
baseUri: https://api.bring.com/shippingguide/products

documentation:
- title: Introduction
  content: |
      The Shipping Guide (Fraktguiden) is a free service from Bring that provides

      * price information,
      * service area (norwegian: dekningsområde), and
      * estimated delivery times.

      With the Shipping Guide it is easy to offer different shipping alternatives to your end customers. Whether they want to

      * get delivery to the door (daytime or evening),
      * pick up the shipment at a post office, or
      * get the shipment delivered to the mailbox

      The Shipping Guide returns the recommended way to present these shipping alternatives, as well as prices and delivery times.

      [Demo shipping alternatives](http://fraktguide.bring.no/fraktguide/demoVelgFraktalternativ.do?from=0484&to=0470&weightInGrams=800&length=10&width=20&height=5&product=servicepakke&product=pa_doren&product=bpakke_dor-dor&product=smaapakker_a-post&product=ekspress09&product=smaapakker_b-post&product=courier_1h&product=minipakke&callbackUrl=http://fraktguide.bring.no/fraktguide/popupCallback.jsp&date=2015-10-07) form (Norwegian).

      The demo shows that the Shipping Guide returns product categories for each request, making a shipping alternatives-page easy to set up. The focus is on delivery methods to the end customer, not product names.

      The Shipping Guide has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality. There are some limitations in the XML/JSON API, such as the inability to mark a parcel as a specialized goods.

      There is also a [Offline SOAP service](http://developer.bring.com/additionalresources/offlinedata.html?from=shipping) for retrieving data for offline use (get complete prices, service area and delivery times based on a fixed sender postal code).

- title: Guidelines
  content: |
      `<MainDisplayCategory>` should be written in bold text and followed by our logo. [Get approved logo here](http://mediaweb.posten.no/fotoweb/Default.fwx?archiveId=5005).

      In the webshop you should display

      * `<MainDisplayCategory>`
      * `<DisplayName>`
      * `<DescriptionText>`

      Repeat the last two as needed, depending on the number of options you would like to display.

      The following values are not meant for display in the webshop and as such should not be visible on your site

      * `<Product>`
      * `<ProductId>`
      * `<ProductCodeInProductionSystem>`

      *We strongly advise that you give your customers at least two options, home delivery and pickup point.*

      | XML | JSON/JSONP | Web services/SOAP |
      |:----|:-----------|:------------------|
      | The XML API is an easy way to integrate with the Shipping Guide using plain HTTP clients. It is also the best API to use when exploring the service using a web browser. | Web browsers can (using JavaScript) retrieve information from external sites if the data are made available in JSONP format. The purpose is that you can paste HTML / Javascript on your web page and easily use data from the Shipping Guide without server components on your web page. See widgets. | The SOAP API has the complete feature set of the Shipping Guide. It requires a SOAP client and the use of our WSDL. It has an Online version (one request per shipment) or an offline version (e.g. nightly fetch prices, service area and delivery times based on a fixed consignor postal code). |

/price{mediaTypeExtension}:
  displayName: Get shipment prices
  securedBy: [mybring_headers, null]
  description: |
      TODO: description
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get shipment prices
    queryParameters:
      from:
        description: Sending from postal code
        type: string
        example: 7600
      to:
        description: Sending to postal code
        type: string
        example: 1407
      weightInGrams:
        description: Weight of package in grams
        type: integer
        example: 1500
      width:
        description: Package width in centimeters
        type: integer
        example: 40
      length:
        description: Package length in centimeters
        type: integer
        example: 40
      height:
        description: Package height in centimeters
        type: integer
        example: 30
      date:
        description: Shipping date specifies which date the parcel will be delivered to Bring (within the timelimit), and is used to calculate the delivery date. Date is specified in ISO-format, YYYY-MM-DD.
        type: date
        example: 2015-11-18
      time:
        description: Shipping time may be specified. Note that Bring's courier products are the only one affected by this parameter. Time is specified in ISO-format, HH:mm.
        type: date
        example: 12:30
      clientUrl:
        displayName: Client URL
        description: To use the Shipping Guide you must specify a client url parameter. The client url should be set to the url of the web shop or application the end user is ordering from. The client url can be sent as a url parameter, clientUrl, or as a header, `X-Bring-Client-URL`.
        type: string
        example: https://www.example.org/webshop
      edi:
        displayName: EDI setting
        description: Flag that tells if the parcel will be registred using EDI when it is shipped. Note that this flag may affect price and which products are available.
        type: boolean
        default: true
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo
      foo:
        description: TODO
        type: string
        example: foo

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
          application/xml:

/expectedDelivery{mediaTypeExtension}:
  displayName: Get estimated delivery time
  securedBy: [mybring_headers, null]
  description: |
      TODO: description
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get estimated delivery time
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
          application/xml:

/all{mediaTypeExtension}:
  displayName: Get shipment prices, estimated delivery and more
  securedBy: [mybring_headers, null]
  description: |
      TODO: description
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get shipment prices, estimated delivery and more
    queryParameters:
      q:
        description: Get shipment prices, estimated delivery time and additional information
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
          application/xml:


Added trait "searchable"

Added trait "searchable"

#%RAML 0.8
---
title: Example HTTP JSON API
baseUri: http://localhost:8080/{version}
version: v1

traits:
 - searchable:
    queryParameters:
     author:
      displayName: Author
      type: string
      description: The author's name of the articles to search.
      example: Kai
      required: false

/articles:
 description: Collection of tech articles
 get:
  is: [
       searchable
      ]
  responses:
   200:
    body:
     application/json:
      schema: |
       {
       	"type":"array",
       	"items": [
         {
          "type":"object",
          "properties":
           {
            "id": { "type": "integer" },
            "content": { "type": "string" }
           }
         }
        ]
       }
 /{articleId}:
  get:
   responses:
    200:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 200
        }
  post:
   responses:
    201:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 201
        }

#%RAML 0.8
---
title: Example HTTP JSON API
baseUri: http://localhost:8080/{version}
version: v1

/articles:
 description: Collection of tech articles
 get:
  queryParameters:
   author:
    displayName: Author
    type: string
    description: The author's name of the articles to search.
    example: Kai
    required: false
  responses:
   200:
    body:
     application/json:
      schema: |
       {
       	"type":"array",
       	"items": [
         {
          "type":"object",
          "properties":
           {
            "id": { "type": "integer" },
            "content": { "type": "string" }
           }
         }
        ]
       }
 /{articleId}:
  get:
   responses:
    200:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 200
        }
  post:
   responses:
    201:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 201
        }


Document rate-limiting in PUP

Document rate-limiting in PUP

#%RAML 0.8
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      ### Rate limiting

      The Pickup point API has a rate limit, primarily considered on a per-user basis. Currently it limits API users to no more than 60 requests within a minute from a single IP address.

      Once you go over the rate limit, you will receive a response with an HTTP response code of 429 (Too Many Requests). The body of the response will consist of the following fields:

      - `code`: `429`
      - `error_message`: `The maximum number of requests per minute has been exceeded.`

      As an additional note, While accessing the Pickup point API together with Shipping Guide API, the product list should be displayed even in the case that the request has been rate limited by the Pickup point API.

      #### High-volume users

      If you're a high-volume user of the Pickup Point API, please [contact Customer Service](http://developer.bring.com/support/) to discuss your options.

      When contacting Bring support include a description of how you are using the Pickup Point API, also an estimate of current request volumes.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HH:mm`. Return only pickup points that are open on or before the specified time.
        type: string
      openOnOrAfter:
        description: Format `HH:mm`. Return only pickup points that are open on or after the specified time.
        type: string
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            example: !include examples/by_postal_code.json
          application/xml:
            example: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        description: |
          Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
        body:
          application/json:
            example: !include examples/filter_address.json
          application/xml:
            example: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        description: |
          If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
        body:
          application/json:
            example: !include examples/filter_search.json
          application/xml:
            example: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        description: |
          If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

          - `ALL_WEEKDAYS` (default)
          - `MONDAY`
          - `TUESDAY`
          - `WEDNESDAY`
          - `THURSDAY`
          - `FRIDAY`
          - `SATURDAY`
          - `SUNDAY`

          If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
        body:
          application/json:
            example: !include examples/filter_days.json
          application/xml:
            example: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        description: |
          If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

          The format of `<time>` is `hhmm`.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
        body:
          application/json:
            example: !include examples/filter_hours.json
          application/xml:
            example: !include examples/filter_hours.xml

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HH:mm`. Return only pickup points that are open on or before the specified time.
        type: string
      openOnOrAfter:
        description: Format `HH:mm`. Return only pickup points that are open on or after the specified time.
        type: string
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            example: !include examples/by_coordinates.json
          application/xml:
            example: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            example: !include examples/by_id.json
          application/xml:
            example: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string

#%RAML 0.8
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HH:mm`. Return only pickup points that are open on or before the specified time.
        type: string
      openOnOrAfter:
        description: Format `HH:mm`. Return only pickup points that are open on or after the specified time.
        type: string
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            example: !include examples/by_postal_code.json
          application/xml:
            example: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        description: |
          Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
        body:
          application/json:
            example: !include examples/filter_address.json
          application/xml:
            example: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        description: |
          If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
        body:
          application/json:
            example: !include examples/filter_search.json
          application/xml:
            example: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        description: |
          If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

          - `ALL_WEEKDAYS` (default)
          - `MONDAY`
          - `TUESDAY`
          - `WEDNESDAY`
          - `THURSDAY`
          - `FRIDAY`
          - `SATURDAY`
          - `SUNDAY`

          If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
        body:
          application/json:
            example: !include examples/filter_days.json
          application/xml:
            example: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        description: |
          If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

          The format of `<time>` is `hhmm`.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
        body:
          application/json:
            example: !include examples/filter_hours.json
          application/xml:
            example: !include examples/filter_hours.xml

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HH:mm`. Return only pickup points that are open on or before the specified time.
        type: string
      openOnOrAfter:
        description: Format `HH:mm`. Return only pickup points that are open on or after the specified time.
        type: string
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            example: !include examples/by_coordinates.json
          application/xml:
            example: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            example: !include examples/by_id.json
          application/xml:
            example: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string


Fix broken link to authentication for pickup-point

#%RAML 0.8
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |

        The Pickup Point API becomes authenticated from 01.11.2020

            Our customers are increasingly demanding new functionality and solutions that are easy to use. To meet these expectations, we must know which customers and partners are using our APIs and how they are using them.

            To further develop the value proposition of our Pickup Point API, the solution becomes authenticated from 01.11.2020.

            We recommend making the adjustment already now, well in advance of summer vacations and peak season.

      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox(address, postalCode) and visiting address(visitingAddress,visitingPostalCode).Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      ### Rate limiting

      The Pickup point API has a rate limit, primarily considered on a per-user basis. Currently it limits API users to no more than 60 requests within a minute from a single IP address.

      Once you go over the rate limit, you will receive a response with an HTTP response code of 429 (Too Many Requests). The body of the response will consist of the following fields:

      - `code`: `429`
      - `error_message`: `The maximum number of requests per minute has been exceeded.`

      As an additional note, While accessing the Pickup point API together with Shipping Guide API, the service list should be displayed even in the case that the request has been rate limited by the Pickup point API.

      #### High-volume users

      If you're a high-volume user of the Pickup Point API, please [contact us](mailto:developer@bring.com) to discuss your options.

      When contacting Bring support include a description of how you are using the Pickup Point API, also an estimate of current request volumes.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk
        - Type 19 : Posten pakkeutlevering
        - Type 21 : Postkontor
        - Type 27 : Pakkeautomat
        - Type 32 : Postpunkt, egendrevet
        - Type 33 : Postpunkt
        - Type 37 : Pakkeboks

      Sweden :
        - Type 34 : Manned

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Authentication
  content: |
      The Pickup Point API requires authentication. To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            example: !include examples/by_postal_code.json
          application/xml:
            example: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        description: |
          Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
        body:
          application/json:
            example: !include examples/filter_address.json
          application/xml:
            example: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        description: |
          If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
        body:
          application/json:
            example: !include examples/filter_search.json
          application/xml:
            example: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        description: |
          If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

          - `ALL_WEEKDAYS` (default)
          - `MONDAY`
          - `TUESDAY`
          - `WEDNESDAY`
          - `THURSDAY`
          - `FRIDAY`
          - `SATURDAY`
          - `SUNDAY`

          If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
        body:
          application/json:
            example: !include examples/filter_days.json
          application/xml:
            example: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        description: |
          If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

          The format of `<time>` is `HHmm`.

          In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
        body:
          application/json:
            example: !include examples/filter_hours.json
          application/xml:
            example: !include examples/filter_hours.xml

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            example: !include examples/by_coordinates.json
          application/xml:
            example: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            example: !include examples/by_id.json
          application/xml:
            example: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            example: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            example: !include examples/default_pickup_point_by_postal_code.xml


*	#hot-fix. articles.raml

*	#hot-fix. articles.raml

#%RAML 1.0
title: My Company API
baseUri: http://my-company.com/{version}
version: v1
mediaType:  application/vnd.api+json
description: My Company API description RAML templates
types:
  ID:
    type: integer
    required: true
  Type:
    type: string
    required: true
    minLength: 1
    maxLength: 255
  DataObject:
    type: object
    required: true
  DataArray:
    type: array
    required: true
  RelationshipsDataItem:
    type: object
    properties:
      id: ID
      type: Type
  TagRelationships:
    description: Tag relationship description
    type: object
    properties:
      data:
        type: DataArray
        items:
          type: RelationshipsDataItem
  TagAttributes:
    description: Always set attributes for object
    type: object
    properties:
      title:
        type: string
        required: true
        minLength: 3
        maxLength: 255
  Tag:
    type: object
    properties:
      type: Type
      id: ID
      attributes: TagAttributes
      relationships:
        type: ArticleRelationships
  ArticleRelationships:
    type: object
    properties:
      data:
        type: DataArray
        items:
          type: RelationshipsDataItem
  ArticleAttributes:
    description: Article attributes description
    type: object
    properties:
      title:
        required: true
        type: string
        minLength: 16
        maxLength: 256
      description:
        required: true
        type: string
        minLength: 32
        maxLength: 1024
      url:
        required: false
        type: string
        minLength: 16
        maxLength: 255
      show_in_top:
        description: Show at the top of main page
        required: false
        type: boolean
      status:
        description: The state of an article
        enum: ["draft", "published", "postponed", "archived"]
  Article:
    type: object
    properties:
      type: Type
      id: ID
      attributes: ArticleAttributes
      relationships: TagRelationships
  FilterID:
    type: string
    pattern: '/^[,\ \d]*$/'
  FilterAttribute:
    type: object
    properties:
      \{attribute\}:
        type: string
      attributes: ArticleAttributes
      relationships: TagRelationships
  JsonApiQuerySearch:
    type: object
    properties:
      page:
        type: object
        properties:
          number:
            type: integer
            required: true
            default: 1
            example: 1
            description: page number
          size:
            type: integer
            required: true
            default: 15
            example: 15
            description: elements per page
      sort:
        type: string
        pattern: "/^[-a-z,\ ]*$/"

/article:
  get:
    queryParameters:
      type: JsonApiQuerySearch
    responses:
      200:
        body:
          application/json.vnd+json:
            type: Article[]
  post:
    body:
      application/json.vnd+json:
        type: Article
    responses:
      200:
        body:
          application/json.vnd+json:
            type: Article
  /{id}:
    get:
      responses:
        200:
          body:
            application/json.vnd+json:
              type: Article
    patch:
      body:
        application/json.vnd+json:
          type: Article
      responses:
        200:
          body:
            application/json.vnd+json:
              type: Article
    delete:
      responses:
        204:
    /relationships/tag:
      get:
        responses:
          200:
            body:
              application/json.vnd+json:
                type: TagRelationships
      post:
        body:
          application/json.vnd+json:
            type: TagRelationships
        responses:
          201:
            body:
              application/json.vnd+json:
                type: TagRelationships
      patch:
        body:
          application/json.vnd+json:
            type: TagRelationships
        responses:
          200:
            body:
              application/json.vnd+json:
                type: TagRelationships
      delete:
        responses:
          204:
    /tag:
      get:
        responses:
          200:
            body:
              application/json.vnd+json:
                type: Tag[]

#%RAML 1.0
title: My Company API
baseUri: http://my-company.com/{version}
version: v1
mediaType:  application/vnd.api+json
description: My Company API description RAML templates
types:
  ID:
    type: integer
    required: true
  Type:
    type: string
    required: true
    minLength: 1
    maxLength: 255
  DataObject:
    type: object
    required: true
  DataArray:
    type: array
    required: true
  RelationshipsDataItem:
    type: object
    properties:
      id: ID
      type: Type
  TagsRelationships:
    description: Tag relationship description
    type: object
    properties:
      data:
        type: DataArray
        items:
          type: RelationshipsDataItem
  TagAttributes:
    description: Always set attributes for object
    type: object
    properties:
      title:
        type: string
        required: true
        minLength: 3
        maxLength: 255
  Tag:
    type: object
    properties:
      type: Type
      id: ID
      attributes: TagAttributes
      relationships:
        type: ArticleRelationships
  ArticleRelationships:
    type: object
    properties:
      data:
        type: DataArray
        items:
          type: RelationshipsDataItem
  ArticleAttributes:
    description: Article attributes description
    type: object
    properties:
      title:
        required: true
        type: string
        minLength: 16
        maxLength: 256
      description:
        required: true
        type: string
        minLength: 32
        maxLength: 1024
      url:
        required: false
        type: string
        minLength: 16
        maxLength: 255
      show_in_top:
        description: Show at the top of main page
        required: false
        type: boolean
      status:
        description: The state of an article
        enum: ["draft", "published", "postponed", "archived"]
  Article:
    type: object
    properties:
      type: Type
      id: ID
      attributes: ArticleAttributes
      relationships: TagsRelationships
  FilterID:
    type: string
    pattern: '/^[,\ \d]*$/'
  FilterAttribute:
    type: object
    properties:
      \{attribute\}:
        type: string
      attributes: ArticleAttributes
      relationships: TagsRelationships
  JsonApiQuerySearch:
    type: object
    properties:
      page:
        type: object
        properties:
          number:
            type: integer
            required: true
            default: 1
            example: 1
            description: page number
          size:
            type: integer
            required: true
            default: 15
            example: 15
            description: elements per page
      sort:
        type: string
        pattern: "/^[-a-z,\ ]*$/"

/article:
  get:
    queryParameters:
      type: JsonApiQuerySearch
    responses:
      200:
        body:
          application/json.vnd+json:
            type: Article[]
  post:
    body:
      application/json.vnd+json:
        type: Article
    responses:
      200:
        body:
          application/json.vnd+json:
            type: Article
  /{id}:
    get:
      responses:
        200:
          body:
            application/json.vnd+json:
              type: Article
    patch:
      body:
        application/json.vnd+json:
          type: Article
      responses:
        200:
          body:
            application/json.vnd+json:
              type: Article
    delete:
      responses:
        204:
    /relationships/tags:
      get:
        responses:
          200:
            body:
              application/json.vnd+json:
                type: TagsRelationships
      post:
        body:
          application/json.vnd+json:
            type: TagsRelationships
        responses:
          201:
            body:
              application/json.vnd+json:
                type: TagsRelationships
      patch:
        body:
          application/json.vnd+json:
            type: TagsRelationships
        responses:
          200:
            body:
              application/json.vnd+json:
                type: TagsRelationships
      delete:
        responses:
          204:
    /tags:
      get:
        responses:
          200:
            body:
              application/json.vnd+json:
                type: Tag[]