Define API routes 💌

[janjagusch]

Here my suggestion for the API specification. You can copy and paste the spec into swagger editor to have a easier overview about the routes I'm suggesting.

swagger: "2.0"
info:
  description: "Example API specification for [article-navigator](https://github.com/janjagusch/article-navigator)."
  version: "1.0.0"
  title: "Article Navigator"
  contact:
    email: "jan.jagusch@gmail.com"
host: "localhost"
basePath: "/v1"
schemes:
  - "http"
paths:
  /supermarkets/{supermarketId}:
    get:
      summary: "Finds supermarket"
      description: "Returns a single supermarket"
      operationId: "getSupermarket"
      produces:
        - "application/json"
      parameters:
        - name: "supermarketId"
          in: "path"
          description: "ID of supermarket"
          required: true
          type: "integer"
      responses:
        "200":
          description: "Successful operation"
          schema:
            $ref: "#/definitions/Supermarket"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Supermarket not found"
  /supermarkets/{supermarketId}/articles:
    get:
      summary: "Finds all articles in supermarket"
      description: "Returns an array of articles"
      operationId: "getArticlesBySupermarket"
      produces:
        - "application/json"
      parameters:
        - name: "supermarketId"
          in: "path"
          description: "ID of supermarket"
          required: true
          type: "integer"
      responses:
        "200":
          description: "Successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/Article"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Supermarket not found"
  /supermarkets/{supermarketId}/sections/{sectionId}:
    get:
      summary: "Finds a section in a supermarket"
      description: "Returns a single section"
      operationId: "getSection"
      produces:
        - "application/json"
      parameters:
        - name: "supermarketId"
          in: "path"
          description: "ID of supermarket"
          required: true
          type: "integer"
        - name: "sectionId"
          in: "path"
          description: "ID of the section"
          required: true
          type: "integer"
      responses:
        "200":
          description: "Successful operation"
          schema:
            $ref: "#/definitions/SupermarketSection"
  /articles/{articleId}:
    get:
      summary: "Finds article"
      description: "Returns a single article"
      operationId: "getArticle"
      produces:
        - "application/json"
      parameters:
        - name: "articleId"
          in: "path"
          description: "ID of article to return"
          required: true
          type: "integer"
      responses:
        "200":
          description: "Successful operation"
          schema:
            $ref: "#/definitions/Article"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Article not found"
  /supermarkets/{supermarketId}/articles/{articleId}/section:
    get:
      summary: "Find section of article in supermarket"
      description: "Returns supermarket section of article in supermarket"
      operationId: "getArticleSection"
      produces:
        - "application/json"
      parameters:
        - name: "supermarketId"
          in: "path"
          description: "ID of the supermarket"
          required: True
          type: "integer"
        - name: "articleId"
          in: "path"
          description: "ID of the article"
          required: True
          type: "integer"
      responses:
        "200":
          description: "Successful operation"
          schema:
            $ref: "#/definitions/SupermarketSection"
        "400":
          description: "Invalid ID supplied"
        "404":
          description: "Article not found"
  /supermarkets/{supermarketId}/shortest_path:
    get:
      summary: "Finds the shortest path between sections in a supermarket"
      description: "Returns an array of supermarket sections"
      operationId: "getShortestPath"
      produces:
        - "application/json"
      parameters:
        - name: "supermarketId"
          in: "path"
          description: "ID of the supermarket"
          required: True
          type: "integer"
        - name: "from_section"
          in: "query"
          description: "ID of the section you start from"
          required: True
          type: integer
        - name: "to_section"
          in: "query"
          description: "ID of the section you go to"
          required: True
          type: integer
      responses:
        "200":
          description: "Successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/SupermarketSection"
  /supermarkets/{supermarketId}/shortest_tour:
    get:
      summary: "Finds the shortest tour to visit selected sections in a supermarket"
      description: "Returns an array of supermarket sections"
      operationId: "getShortestTour"
      produces:
        - "application/json"
      parameters:
        - name: "supermarketId"
          in: "path"
          description: "ID of the supermarket"
          required: True
          type: "integer"
        - name: "visit_sections"
          in: "query"
          description: "Array of section IDs you want to visit"
          required: True
          type: "array"
          items:
            type: "integer"
      responses:
        "200":
          description: "Successful operation"
          schema:
            type: array
            items:
              $ref: "#/definitions/SupermarketSection"
definitions:
  SupermarketSection:
    type: "object"
    required:
      - id
      - location
      - type
    properties:
      id:
        type: "integer"
        format: "int64"
      location:
        type: object
        required:
          - x
          - y
        properties:
          x:
            type: integer
          y:
            type: integer
      type:
        type: "string"
        enum: ["entrance", "isle", "checkout"]
  Supermarket:
    type: "object"
    required:
      - id
      - name
      - sections
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
        example: "Lidl Heidelberg"
      sections:
        type: "array"
        items:
          $ref: "#/definitions/SupermarketSection"
  Article:
    type: "object"
    required:
      - id
      - name
    properties:
      id:
        type: integer
      name:
        type: string
        example: "Nutella"
      imageUrl:
        type: string
        format: url

Update: Added /supermarkets/{supermarketId}/sections/{sectionId}.