swagger: "2.0"
info:
version: "47.0.0"
title: Fortellis Sample Application
description: |
# Fortellis Products - Fortellis Domain - Fortellis Spec
For the product, enter the product that the API should promote.
For the domain, enter one of the following Fortellis domains.
* Vehicles Sales
* Document
* Service
* CRM
* Vehicle Media
* Data
* Payment
For the name, enter the common name that you would like to provide for the specification.
# What does this API do?
Spec Providers can supply excellent specs to encourage the adoption and the implementation of those specs by others within the automotive space. Specs should include descriptions that start with an executive summary of what solution and implementations could do with the spec. The description should then provide information on specifically what features the specification offers. Finally, the description should explain how solution and implementation providers can use the spec to achieve personal, departmental, and organizational goals. With this format, Spec Providers can show the value and benefit of the spec outside of their organization and encourage the adoption of their spec by other providers and solutions, increasing the possible implementations, solutions, and users of their APIs and solutions.
# Intended Audience
Spec Providers that are trying to create specs that can pass the linter requirements can start with this spec and replace this placeholder text with the information that suits their specs.
contact:
name: Developer Evangelists
url: https://fortellis.io/contact-us
email: [email protected]
# To submit the YAML file quickly and save you time, you can use the following example to help you format your YAML file. Include a pipe in the description to make the YAML file reflect Markdown. You must include three headings in the description. Include the following information in this format in the first heading: Product Name - Root Name - API Name. The product name is the name of the product or company. The root name is the domain that the API will go under. The intended audience is who should use this API. Include information for what the API does in the next heading. In the third heading, include the intended Audience.
basePath: /sales/parts-store/v47
schemes:
- https
tags:
- Testing Tag
securityDefinitions:
permission-model:
type: oauth2
flow: implicit
authorizationUrl: https://identity.fortellis.io/oauth2/
scopes:
anonymous: Permissions to query and read parts
security:
- permission-model:
- 'anonymous'
# Remove the host. Functionally, this will provide no information on the Fortellis platform. Fortellis solutions call api.fortellis.io/basePath. Fortellis routes the calls to the providerURL/basePath. If you use the app.swaggerhub.com website, you can test the information in your API calls with a solutions before you have completely built the API, but delete the host information before submitting the spec to Fortellis (Find out if this is true and if the API actually works).
host: api.fortellis.io
# Describe the endpoints and the different headers, query parameters, path parameters, and body requests and responses that Solution and API Providers will use.
paths:
# You can create multiple paths with multiple verbs. Please use only accepted OpenAPI spec verbs (Post, Get, Put, Delete).
/all-product-info:
get:
summary: Server example operation
description: You can use this call to get the information on all of the products at this resource that you need to use.
operationId: allProductInfo
parameters:
- $ref: "#/parameters/header.Pididle"
- $ref: "#/parameters/header.Organization"
- $ref: "#/parameters/header.Request-Id"
- $ref: "#/parameters/header.Subscription-Id"
- $ref: "#/parameters/header.Authorization"
- $ref: "#/parameters/query.email"
consumes:
- application/json
produces:
- application/json
responses:
'200':
$ref: "#/responses/AllProducts"
'400':
$ref: "#/responses/BadRequest"
'401':
$ref: "#/responses/Unauthorized"
'403':
$ref: "#/responses/Forbidden"
'503':
$ref: "#/responses/ServiceUnavailable"
tags:
- query
externalDocs:
description: Find more info here.
url: https://swagger.io
/all-product-info/{productNumber}:
get:
tags:
- query
summary: Specific Product
description: Find a specific product.
operationId: productInformation
parameters:
- $ref: "#/parameters/header.Pididle"
- $ref: "#/parameters/header.Organization"
- $ref: "#/parameters/path.productNumber"
- $ref: "#/parameters/header.Request-Id"
- $ref: "#/parameters/header.Subscription-Id"
- $ref: "#/parameters/header.Authorization"
consumes:
- application/json
produces:
- application/json
responses:
'200':
$ref: "#/responses/PathProductNumber"
'400':
$ref: "#/responses/BadRequest"
'401':
$ref: "#/responses/Unauthorized"
'403':
$ref: "#/responses/Forbidden"
'503':
$ref: "#/responses/ServiceUnavailable"
/all-product-info/{productNumber}/product-size:
get:
tags:
- query
summary: Specific Product Description
description: Find the description for a specific product.
operationId: productDescription
parameters:
- $ref: "#/parameters/path.productNumber"
- $ref: "#/parameters/header.Request-Id"
- $ref: "#/parameters/header.Subscription-Id"
- $ref: "#/parameters/header.Authorization"
consumes:
- application/json
produces:
- application/json
responses:
'200':
$ref: "#/responses/ProductSize"
'400':
$ref: "#/responses/BadRequest"
'401':
$ref: "#/responses/Unauthorized"
'403':
$ref: "#/responses/Forbidden"
'503':
$ref: "#/responses/ServiceUnavailable"
/ping:
get:
tags:
- query
summary: Server heartbeat operation
description: Solutions can use this operation to check that the server is still available and responding to requests.
operationId: healthMonitor
parameters:
- $ref: "#/parameters/header.Request-Id"
- $ref: "#/parameters/header.Subscription-Id"
- $ref: "#/parameters/header.Authorization"
consumes:
- application/json
produces:
- application/json
responses:
'200':
$ref: "#/responses/Ping"
'400':
$ref: "#/responses/BadRequest"
'401':
$ref: "#/responses/Unauthorized"
'403':
$ref: "#/responses/Forbidden"
'503':
$ref: "#/responses/ServiceUnavailable"
# Define the parameters that you will use in your spec. You will repeat these multiple times throughout the definition. Some of these items will be common header values that your backend system will expect. Some of them will be unique path values that capture the individual values of each of your systems.
parameters:
header.Request-Id:
name: Request-Id
in: header
required: true
type: string
format: guid
description: A correlation ID that should be returned back to the caller to indicate the return of the given request
header.Subscription-Id:
name: Subscription-Id
in: header
required: true
type: string
format: guid
description: The Fortellis Marketplace subscription identifier between a user entity and the solution. For sample responses use the Subscription-Id 'test'.
header.Authorization:
name: Authorization
in: header
required: true
type: string
format: guid
description: Provides authorization to access Fortellis APIs. For calling a Fortellis Provider, this must be an OAuth 2.0 token issued by the Fortellis authorization server, but you may call the simulator platform with Basic Authorization using your API key and secret.
header.Pididle:
name: User-Id
in: header
description: Identifies the user accessing the account
required: true
type: string
header.Organization:
name: Organization
in: header
description: Identifies the organization that the user is in
required: true
type: string
path.productNumber:
name: productNumber
in: path
description: Filters for a specific product
required: true
type: number
path.productSize:
name: productSize
in: path
description: Filters for the product size of a specific product
required: true
type: string
query.email:
name: email
in: query
description: Filters customers by email address
type: string
query.name:
name: name
in: query
description: Filters customers by name
type: string
query.phone:
name: phone
in: query
description: Filters customers by phone number
type: string
responses:
ProductSize:
description: This sends the product size for a particular product to help you determine if you have the inventory space for that product.
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/ProductSize"
PathProductNumber:
description: This sends the information on a particular product based on the product number.
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/PathProductNumber"
AllProducts:
description: This sends a response with all the products, their size, and their location.
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/AllProducts"
BadRequest:
description: 400 - Bad Request
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/ErrorResponse"
Unauthorized:
description: 401 - Unauthorized
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/ErrorResponse"
Forbidden:
description: 403 - Forbidden
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/ErrorResponse"
NotFound:
description: 404 - Not Found
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/ErrorResponse"
InternalServerError:
description: 500 - Internal Server Error
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/ErrorResponse"
ServiceUnavailable:
description: 503 - Service Unavailable
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/ErrorResponse"
Ping:
description: 200 - OK
headers:
Request-Id:
type: string
schema:
$ref: "#/definitions/Health"
#Define definitions for the return values. You can start to make the information that you want each of your endpoints to return.
definitions:
Health:
description: This is the code that tells you the server is okay.
type: object
properties:
message:
type: string
code:
type: number
links:
type: object
properties:
self:
type: object
properties:
href:
type: string
method:
type: string
allProductInfo:
type: object
properties:
href:
type: string
method:
type: string
thisProductInfo:
type: object
properties:
href:
type: string
method:
type: string
thisProductSize:
type: object
properties:
href:
type: string
method:
type: string
required:
- message
- code
- links
example:
message: The server is up
code: 200
links:
self:
href: '/ping'
method: 'GET'
allProductInfo:
href: '/all-product-info'
method: 'GET'
thisProductInfo:
href: '/all-product-info/{productNumber}'
method: 'GET'
thisProductSize:
href: '/all-product-info/{productNumber}/product-size'
method: 'GET'
ProductSize:
description: This describes the dimensions of the product to help determine if you have the space to store the product.
type: object
properties:
productWidth:
type: string
productHeight:
type: string
productLength:
type: string
productWeight:
type: string
links:
type: object
properties:
self:
type: object
properties:
href:
type: string
method:
type: string
allProductInfo:
type: object
properties:
href:
type: string
method:
type: string
thisProductInfo:
type: object
properties:
href:
type: string
method:
type: string
ping:
type: object
properties:
href:
type: string
method:
type: string
required:
- productWidth
- productHeight
- productLength
- productWeight
- links
example:
productWidth: 4 inches
productHeight: 1.8 cm
productLength: 4 inches
productWeight: 22 g
links:
self:
href: '/all-product-info/all-product-info/{productNumber}/product-size'
method: 'GET'
allProductInfo:
href: '/all-product-info'
method: 'GET'
thisProductInfo:
href: '/all-product-info/{productNumber}'
method: 'GET'
ping:
href: '/ping'
method: 'GET'
PathProductNumber:
description: This gives you the unique identifier for the product.
type: object
properties:
name:
type: string
id:
type: string
number:
type: integer
location:
type: string
productSize:
type: object
properties:
productWidth:
type: string
productHeight:
type: string
productWeight:
type: string
links:
type: object
properties:
self:
type: object
properties:
href:
type: string
method:
type: string
allProductInfo:
type: object
properties:
href:
type: string
method:
type: string
thisProductSize:
type: object
properties:
href:
type: string
method:
type: string
ping:
type: object
properties:
href:
type: string
method:
type: string
required:
- id
- name
- links
example:
name: Radiator
id: SomeExampleId
number: 5
location: 9th & 10th floor, Binarius Building, Deepak Complex National Games Road, Opp Golf Course, Shastrinagar, Yerawada, Pune, Maharashtra 411006, India
ProductSize:
productWidth: 19-3/4 inches
productHeight: 19-1/8 inches
productLength: 2-3/16
productWeight: 17.8 lbs.
links:
self:
href: '/all-product-info/{productNumber}'
method: 'GET'
allProductInfo:
href: '/all-product-info'
method: 'GET'
thisProductSize:
href: '/all-product-info/all-product-info/{productNumber}/product-size'
method: 'GET'
ping:
href: '/ping'
method: 'GET'
AllProducts:
description: This endpoint gives the information on all of the products.
type: object
properties:
products:
type: array
items:
type: object
properties:
name:
type: string
description: The name of the pet
id:
type: string
productSize:
type: object
properties:
name:
type: string
number:
type: integer
location:
type: string
productSize:
type: object
properties:
productWidth:
type: string
productHeight:
type: string
productWeight:
type: string
links:
type: object
properties:
self:
type: object
properties:
href:
type: string
method:
type: string
thisProductInfo:
type: object
properties:
href:
type: string
method:
type: string
thisProductSize:
type: object
properties:
href:
type: string
method:
type: string
ping:
type: object
properties:
href:
type: string
method:
type: string
required:
- products
example:
products:
- name: Gasket
id: G45k3T
number: 4960
location: 8601 Ranch to Market 2222 Building 1 Austin, TX 78730
ProductSize:
productWidth: 4 inches
productHeight: 1.8 cm
productLength: 4 inches
productWeight: 22 g
- name: Chasis
id: Ch4515
number: 8321
location: CDK Global, 1 Cygnet Way, Charnham Park, Hungerford RG17 0YL, UK
ProductSize:
productWidth: 7 ft
productHeight: 1 ft
productLength: 12 ft
productWeight: 250 lbs
- name: Steering Wheel
id: 5T3eR1Ng Wh331
number: 7629
location: 2525 SW 1st Ave Suite 400, Portland, OR 97201
ProductSize:
productWidth: 14 1/2 inches
productHeight: 3 5/8 inches
productLength: 14 1/2 inches
productWeight: 385 grams
- name: Engine
id: 3Ng1N9
number: 2385
location: 1950 Hassell Rd, Hoffman Estates, IL 60169
ProductSize:
productWidth: 28 inches
productHeight: 27 inches
productLength: 26 inches
productWeight: 411 lbs.
- name: Radiator
id: R4d14t0R
number: 3897
location: 9th & 10th floor, Binarius Building, Deepak Complex National Games Road, Opp Golf Course, Shastrinagar, Yerawada, Pune, Maharashtra 411006, India
ProductSize:
productWidth: 19-3/4 inches
productHeight: 19-1/8" inches
productLength: 2-3/16
productWeight: 17.8 lbs.
links:
self:
href: '/all-product-info'
method: 'GET'
thisProductInfo:
href: '/all-product-info/{productNumber}'
method: 'GET'
thisProductSize:
href: ''
method: '/all-product-info/{productNumber}/product-size'
ping:
href: '/ping'
method: 'GET'
ErrorResponse:
description: Common error response object.
properties:
code:
type: integer
format: int32
message:
type: string
required:
- code
- message
example:
code: 400
message: Bad Request
# 9th & 10th floor, Binarius Building, Deepak Complex National Games Road, Opp Golf Course, Shastrinagar, Yerawada, Pune, Maharashtra 411006, India
# Added by API Auto Mocking Plugin
# host: api.fortellis.io
# Added by API Auto Mocking Plugin
# basePath: /nathansandberg/Demo-API-Spec/1.0.0
# Added by API Auto Mocking Plugin