I'm new to this api documentation era.
Vising this api documentation, I get to post and query data. I understand that's a demo api documentation with swagger.
But what happens with real world API documentation? do I have a documentation in demo.api.myawesome.com and actual api on api.myawesome. com using different data stores?
But again digging deeper, I got to find out that an api can be self documenting using swagger libraries. This seems like both api and documentation are using the same data store which can't be the case.
What am I missing here?
From the Swagger website:
Swagger is a set of rules (in other words, a specification) for a format describing REST APIs. The format is both machine-readable and human-readable. As a result, it can be used to share documentation among product managers, testers and developers, but can also be used by various tools to automate API-related processes.
So yes, it uses the same "back end" as the actual API. It's just visualizing it, allowing you to interact with it via the Swagger UI.
If you mean Swagger UI - the "try it out" button sends requests to the server specified by the host property in your spec. If host specifies your production server, requests will be sent to production; if it points to a sandbox, "try it out" will use the sandbox. You may have a version of the spec for internal use that points to production, and a public version that points to sandbox.
Note that Swagger supports authentication as a way to ensure that only authorized users (e.g. your actual customers with valid credentials or API keys) can make API calls.
You can omit host from the spec to disable the "try it out" functionality - this way you can still have the API docs, just without the interactive part.
Related
To get started quickly with API Connect, I just want to import a Swagger spec of an existing service and make this service a managed API in API Connect.
API Connect provides an import function for YAML files, but the API can not be tested.
I've seen this scenario several times, so I though it might be useful to have some documentation on this.
When importing a swagger specification, you need to modify a few settings to transform this service definition into an API definition (even though they are quite similar). You need to modify the following parameters:
Schemes https - The Gateway enforces HTTPS
Host: $(catalog.host) - This variable links to the current host (in a certain catalog)
Then, you need to build an assembly. The proxy policy is well suited for building facades, as all content from Headers, Body, etc. is re-routed. For the URL, enter the URL of the endpoint + a context variable that refers to the incoming path, like:
http://example.com$(request.path)
I have created a small video on Youtube to demonstrate the neccessary steps.
There is three Types like Enforced,Test,CORS. What would happen if we disabled them?
The lifecycle states (phases) are:
Identified (have identified that there is a need for an api that
provides a specific capability)
Specified (have started to flesh out
what the API externals will look like)
Realized (there is an actual backend to the API and can invoke and use it)
The other three options are related but aren't really "lifecycle states".
Enforced == whether the API will be managed by API Connect - is it deployed to the gateway? Disable this and the API will not be deployed out to the gateway, no analytics will be tracked on its usage, there will be no subscription management, etc... Basically turning this off means you need to have the actual API backend in the swagger document and have purely loaded it into APIC for socialisation / documentation purposes. It will not be managed by APIC.
Testable == do you want to allow users to test this API from the portal test tool ?
CORS == Do you want to enable Cross-Origin Resource Scripting support (this is required to invoke the API from any AJAX application anywhere - including the test tools in both API Manager and the portal)
If you have testable == true then you either need cors == true or you have to implement all the OPTIONS requests in your API manually. The test tool won't work otherwise.
I have created some APIs in API management layer, which are essentially proxies between the calling client and an underlying web api.
I did this by importing the swagger file of the underlying API, and then adding the newly created API to a Product, repeating this for each separate proxy that I needed. This means then that the underlying API could be called but not without the subscriber key of the product that the newly created API was attached to.
Is it possible to do something similar with API apps, i.e. creating API apps using just the swagger file from the underlying API in the azure portal, that act as proxies between the calling client and an underlying web api (as below)?
Do you mind expanding on why do you need to have API Apps acting as proxies?
I am not aware of such capability for API Apps specifically. There are Swagger-based code generation tools available, for example on http://swagger.io/open-source-integrations/. So perhaps you will be able to find something that would work for you.
When creating a site/script to be on the client end of a RESTful API, what tools are available to create a "workbench" to explore the API, examining headers and responses while working through the design? Preferably one(s) that allow you to enter a custom endpoint, and create sample requests to see the responses. I recall seeing one nice workbench before, but its name has escaped me.
Re-found the one I remembered: The Apigee Console is a great interface for playing around with an existing API or building your own.
Mashery's I/O Docs is an open source workbench that you can deploy yourself on a Node.js server with Redis for storage.
If you have the wadl file of the ReST Services, you can load it in SOAP UI and use it.
EditedAnother much simpler tool Rest Client
If you have ever used the Flickr API, you'll be familiar with their API Explorer. It is an awesome tool, that allows you to view the documentation for each API method, and the killer feature, being the execution of that API method (with a form to populate any request parameters). It even picks up when you are logged in, and completes the authentication part on your behalf. Gowalla has a similar API Explorer that is also really good.
Are there are tools for WCF that will auto-generate such an API Explorer, free or commercial?
Currently, we use Fiddler to build the JSON requests, but I would like to publish these service contracts, and allow potential developers to play around with them via a web based API explorer.
I am aware of the WCF Web HTTP Service Help Page, which I am using (and is awesome), but it is the API Explorer part that I am interested in.
You may want to look at I/O Docs - an open-sourced interactive documentation system for RESTful web APIs that any API owner can use to deploy for their own documentation. It runs on Node.js and uses Redis as a data store.
https://github.com/mashery/iodocs
Example: developer.klout.com/iodocs, developer.rottentomatoes.com/iodocs
It uses JSON schema based files to define API endpoints, method and parameters. Based on these JSON files, it generates a client interface that developers can use to learn and explore your API. API calls can be executed directly from the documentation interface, producing formatted responses.
It's Open-sourced, so you can be assured of regular updates and improvements. In fact this past weekend, Brandon West from SendGrid (who use I/O docs to power their documentation), created and open sourced the UI to create/edit the JSON schema files for I/O Docs. So you don't have to manually create the JSON files anymore.
https://github.com/brandonmwest/iodoctor
Not exactly what you were looking for, but....
WCF provides something called the WCF Test Client, for this purpose.
If you install Visual Studio, you get it. For example, for VS2008, installed in the usual place, you can find the WCF Test Client (WcfTestClient.exe) in the following location:
C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\
Take a look at Apigee: http://apigee.com/