-
Notifications
You must be signed in to change notification settings - Fork 1
Using the JS Library
<script src="https://console.rest/github.io/libs/console-rest-api.js"></script>This library is separated in 3 parts:
-
A web worker that does all the heavy lifting, such as as converting in between file formats, detecting formats, etc. This web worker is by default using the API-Flow library (https://github.com/luckymarmot/API-Flow) to do so.
-
A main-thread wrapper that interacts with the web worker in a relatively raw fashion.
-
A set of nice methods to interact easily with the wrapper, grouped in a simple library called
ApiFlow.
const converter = new ApiFlow()
converter.set({
mode: 'url',
url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
name: 'Instagram API'
}).convert({
target: {
format: 'raml',
version: 'v1.0'
}
}).then(converted => {
console.log('converted content', converted)
}, error => {
console.error('failed to convert with error', error)
})const converter = new ApiFlow()
converter.set({
mode: 'text',
text: 'curl -X GET https://xkcd.com/info.0.json',
name: 'Current XKCD API'
}).convert({
target: {
format: 'swagger',
version: 'v2.0'
}
}).then(converted => {
console.log('converted content', converted)
}, error => {
console.error('failed to convert with error', error)
})const converter = new ApiFlow()
converter.set({
mode: 'url',
url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
name: 'Instagram API'
}).detect('format').then(format => {
console.log('format of source is', format)
}, error => {
console.error('failed to detect format with error', error)
})const converter = new ApiFlow()
converter.set({
mode: 'url',
url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
name: 'Instagram API'
}).detect('name').then(format => {
console.log('suggested name for source is', name)
}, error => {
console.error('failed to detect name with error', error)
})A common usage pattern is to convert one source file in multiple formats. It is recommended to use converter.load to pre-fetch this, so that each conversion attempt does not reload the content.
const converter = new ApiFlow()
converter.set({
mode: 'url',
url: 'https://api.apis.guru/v2/specs/xkcd.com/1.0.0/swagger.json',
source: {
format: 'swagger',
version: 'v2.0'
}
})
.load() //loaded once asynchronously
const RAML1Promise = converter.convert({
target: {
format: 'raml',
version: 'v1.0'
}
}) // automatically use the pre-loaded content once it's ready
const Swagger3Promise = converter.convert({
target: {
format: 'raml',
version: 'v3.0'
}
}) // automatically use the pre-loaded content once it's ready
const OverridingPromise = converter.convert({
mode: 'url',
url: 'https://api.apis.guru/v2/specs/xkcd.com/1.0.0/swagger.json',
target: {
format: 'raml',
version: 'v3.0'
}
}) // does not use the pre-loaded content-
set: a setter to update the internal settings of the converter. -
load: a utility tool that tries to load content from raw text, urls or from a selector. -
detect: a method to infer a few properties about a file. -
convert: a method to convert a file from one format to another. -
start: a method to start the web worker bound to this converter. -
close: a method to stop the web worker bound to this converter.
This setter updates the internal settings of the converter. These settings will be applied when using other methods such as detect or convert, unless overridden.
converter.set has two possible arguments format:
converter.set(key, value)converter.set(obj)
The set of key values that can be set using this method is:
{
mode: 'url',
url: 'https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.json',
text: null,
selector: null,
name: 'Instagram API',
source: {
format: 'swagger',
version: 'v2.0'
},
target: {
format: 'swagger',
version: 'v3.0'
}
}converter.set returns converter, so as to allow chaining.
This method allows the converter to pre-load a resource that can then be used for conversions. It supports multiple resource locations such as a raw String (text), a remote resource (url) or a local DOM resource (selector).
-
Obj(optional). An object that contains settings about where to find the resource. If no object is provided, the default settings will be used.
converter.load returns an ES6 Promise. Once the content has been loaded successfully, it is also available at converter.content.
This method helps the converter infer informations about its source resource. It can infer both the format and name of the resource.
-
action[required]. the property to detect. must be one of[ format, name ]. -
content(optional). A resource from which to infer the property. If no content is provided, the default content will be used. If no default content can be found,load()will be called.
converter.detect returns en ES6 Promise. Once the property has successfully been inferred, it is also available at either converter.source or converter.name
This is the core method of ApiFlow and Console.REST. It transforms a resource from one file format to another.
-
obj(optional) An object that contains settings about the resource, its format, and the target format. If no object is provided, the default settings will be used.
converter.convert returns an ES6 Promise.
It is possible to use your own web worker wrapper, provided that it respects the expected behavior for such worker wrapper.
const workerWrapper = new MySpecialWorkerWrapper()
const converter = new ApiFlow(workerWrapper)It is possible to use your own ApiFlow library, rather than the default one.
const converter = new ApiFlow()
converter.start('https://my-intranet-server/externals/api-flow.js')