NASA Proceeds to Mars

    soas

    0.5.1 • Public • Published

    Semantic Open API Specification library

    Holds utility functions to manipulate an API described with OpenAPI 3.0 specification and semantically annotated.

    Quick start

    npm install --save
    
    import soasLoader from 'soas'
    import apiDoc from 'path-to/my-api.json'
    
    const soas = soasLoader(apiDoc)
    
    const endPoints = soas.endPoints()
    const actions = soas.actions()
    
    const input1 = {
      "http://schema.org/streetAddress": "7 Rue Victor Schoelcher",
      "http://rdf.insee.fr/def/geo#codeCommune":"22050"
    }
    const output1 = await soas.execute('getCoord', input1)
    // output1 is :
    // {"http://schema.org/identifier":"1",
    // "http://schema.org/latitude":"48.3",
    // "http://schema.org/longitude":"-3.4"}
    
    // works with streams too
    const input2 = fs.createReadStream(path.join(__dirname, 'addresses.ndjson'))
                      .pipe(mimeTypeStream('application/x-ndjson').parser())
    const output2 = await soas.execute('postCoords', input)
    output2.pipe(mimeTypeStream('application/x-ndjson').serializer()).pipe(process.stdout)
    ...

    Documentation

    Constructor

    See the OpenAPI 3.0 specification for the correct format of the API description.

    import soasLoader from 'soas'
    import apiDoc from 'path-to/my-api.json'
    
    // apiDoc is a JSON describing an API with the OpenApi 3.0 specification
    // To keep this library light, schema validation is not handled
    const soas = soasLoader(apiDoc)

    endPoints()

    List API endpoints. Return an array of objects with the following properties :

    • method : the HTTP method
    • path : the path this endpoint refers to
    • operation : the operation described by this endpoint. See the Operation Object

    actions()

    List all actions. An action is an API endpoint semantized with annotations described here. It has the followings properties :

    • id : the identifier of the action
    • type : the type of action. This should be a subtype of schema.org Action, or something similar.
    • operation : path and method
    • input : an map of concepts => parameters location
    • inputCollection : boolean indicating if the action takes a collection as input
    • inputBodyTypes : the possible mime-types for the request body, if there is one
    • output : an map of concepts => object fields
    • outputSchema: The JSON schema of output
    • outputCollection : boolean indicating if the action outputs a collection
    • outputBodyTypes : the possible mime-types for the response body, if there is one
    • summary : the summary of the operation this action refers to
    • canUse : a boolean indicating if this library is able to use the action or not

    execute(actionId [, input, server])

    Return a promise. Once resolved, can be an object or a stream of objects which are maps of concepts and their value.

    actionId is the id of an action listed with actions(). input is is a map of concepts and their value. It can be a stream of objects too. server is an url to query, if not provided it will be resolved to the url of the first Server Object of the servers property of the API description.

    Keywords

    none

    Install

    npm i soas

    DownloadsWeekly Downloads

    7

    Version

    0.5.1

    License

    MIT

    Unpacked Size

    13 kB

    Total Files

    4

    Last publish

    Collaborators

    • albanm
    • bonnel-n