Forums: 
Q&A
Joe Ernst
April 3 2018 at 2:57 PM

I see you have a list of several Sales and Service APIs that are obviously the first of many APIs to be published on the platform, but I can't connect the dots between the API Producer, Fortellis, and the API Consumer.

  1. It appears that Fortellis defines the API specs, but I don't see any implementations of the APIs.  Will there be a list of implementations to choose from for each API?  What is the distinction between "APIs" and "My APIs"?
  2. What is the "Try it out" button connected to?  I keep getting 401 Unauthorized No Valid API key, even though I am using the API key I got when I defined a sandbox App.
  3. How is OAuth implemented? Using this OAuth tutorial as a reference, which OAuth Scheme are you using?  I think we need some diagrams that clearly show the relationships (and boundaries) between Producers, Consumers, and the Fortellis network itself.
  4. Are you using the OpenAPI Specification (formerly Swagger) for the YAML API specification files? 

I guess that's enough for now.  I'll have more questions depending on the answers to the first four.

Michael Claiborne
April 4, 2018 at 10:08 AM

Agreed that more docs would be helpful.  For me, I would like to see

1) Specs for the APIs. I can play around with them and deduce some, but need docs to really understand them. For their old API CDK published the "Merchandisable Vehicle Service Technical Spec" which was very helpful.

2) A description of the overall marketplace vision. Will Fortellis define a standard APIs and allow different vendors to publish implementations of those APIs? (e.g. JDBC model) Or does each vendor define their own APLs?

3) Some expectation of if and when other services will appear. Credit check, vehicle history, OEM discounts, trade-in valuation, F&I product info, etc.

I love the first steps!

Mike

Abram Goldshtein
April 5, 2018 at 12:50 AM

Hello Joe, welcome to the Fortellis Developer Community!

I’ll answer your questions here, and I would be happy to have a follow-up with you over the phone.

1. The “My APIs” section is for any ISV/Developer or organization who would like to publish an API to their respective backend service for others to consume through the platform. When you publish an API, you have a visibility control with either Public or Private setting. If you set the control to Public, your API will become available on the “APIs” section of the Developer Network, after the review and approval process is completed.
Fortellis builds the API blueprint for a select Domain. Within each domain, there are CDK published APIs available today that are implemented to back end services. So for example, if you are looking for “Vehicle Sales” specific information, the three available implementations are as follows:

Deal Creation Quotes API
Calculate Payments API
Merchandisable Vehicles API

Appointment API
Service Pricing API
Repair Orders API

2. I’d like to help you with the 401 error you received. Looking at the APIs you selected in My Apps, you may be using an API key for a different app. For example, an API key for Service Packages, will only work for Service Packages. If you want to test a different app using the “Try it Out” tool, you will need to subscribe to its respective API. Please let me know if you continue to have any problems and we can try it together.

3. OAuth setup and documentation is in final review and will be released soon. However, here is the documentation and sample code that will help your back-end securely communicate with our platform.

Here is a link to the topic.
https://community.fortellis.io/community/blog/how-can-i-try-out-api 
Once you have the key in hand, your back-end can use that key to talk to the platform.

4. You are correct! The blueprint for the YAML spec files are using OpenAPI standards.
Thank you for all the great questions! We'll do our best to answer any remaining questions you have and soon have the updated documentation you requested!

Joe Ernst
April 5, 2018 at 10:26 AM

Thanks for the reply Abram, here are my responses:

1. You say "Fortellis builds the API blueprint for a select Domain".  Does that mean if my API needs a new Domain, or needs new API endpoints in an existing Domain, that Fortellis will need to define them first? 

There's a disconnect between the API definitions and implementations.  I'm finding this part confusing because I see the API definitions that you mentioned, but I expected to also see something like "Access the CDK implementation of this API here".  

2. I think you were correct.  I must have been trying to use an API that my app is not registered to use.  When I tried a Service API it seems to work.

3. I will be (im)patiently awating the OAuth docs. ;-)  I want to publish an API, so as a Producer, I need to understand how to enable Fortellis to make calls back to my API on my domain.

4. I have my YAML file created, now I just need to get terms, privacy, and pricing from the business side of the house.  Will the Fortellis platform handle the billing, or do we just invoice consumers of our API individually?

Thanks again for your help, I am very excited to see what this platform can do!