GithubHelp home page GithubHelp logo

linode / linode-api-docs Goto Github PK

View Code? Open in Web Editor NEW
22.0 19.0 63.0 11.17 MB

Source for the Linode API v4 Docs

Home Page: https://www.linode.com/docs/api/

License: Apache License 2.0

Shell 44.31% Python 55.69%
linode linode-api docs

linode-api-docs's Introduction

Linode OpenAPI 3

Build Status

This is the Linode API OpenAPI 3 Schema

Requirements

The linter used for the OpenAPI spec is written in python3. A virtualenv is recommended for local work.

virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt

Development

The spec can be linted using the openapi3 module.

python -m openapi3 openapi.yaml

Versioning

When making a new release you must tag the release with the correct semantic versioning-compliant version string so that all versions are populated appropriately. There is a ./bin/deploy helper which will help with this process.

./bin/deploy 0.1.0

Spec Extensions

The OpenAPI specification supports vendor-specific extensions prefixed with an x- in the attribute name. The following extensions are created by Linode for use in our spec:

Attribute Location Type Supported By Explanation
x-linode-filterable schema properties boolean If true, indicates that this property may be included in an X-Filter header
x-linode-grant method string The level of access a user must have in order to call this endpoint.
x-linode-cli-display schema properties integer linode-cli If truthy, this property will be displayed in the Linode CLI. The numeric value determines the ordering of the displayed columns, left to right.
x-linode-cli-color schema properties object linode-cli A mapping of possible property values to color codes understood by python's colorclass module. Must include a default_, used for any value that doesn't match one of the keys.
x-linode-cli-format schema properties string linode-cli Overrides the value of the "format" field for this property, but for the CLI only. Valid values are file and json.
x-linode-cli-command path string linode-cli The command group the methods of this path fall into when generating commands in the linode-cli <command> <action> format.
x-linode-cli-action method string linode-cli The action this method will be mapped to when generating commands in the linode-cli <command> <action> format.
x-linode-cli-skip method boolean linode-cli If true, the CLI will not expose this action.
x-linode-redoc-load-ids operation boolean If true, ReDoc will load this path and print a bulleted list of IDs. This only works on public collections.
x-linode-ref-name keyword string Linode Developer's Site Provides a mechanism by which the Developer's site can generate a dropdown menu with an Object's name when using the oneOf keyword with a discriminator. Note: This front end functionality is currently being developed.
x-linode-cli-rows media type array linode-cli A list of JSON paths where the CLI can find the value it should treat as table rows. Only needed for irregular endpoints.
x-linode-cli-use-schema media type schema or $ref linode-cli The schema the CLI should use when showing a row for this response. Use with x-linode-cli-rows.
x-linode-cli-nested-list media type string linode-cli The name of the property defined by this response body's schema that is a nested list. Items in the list will be broken out into rows in the CLI's output.
x-linode-cli-allowed-defaults requestBody list of string linode-cli A list of defaults this action should accept from the CLI. Valid values are "region", "type", and "image"

linode-api-docs's People

Contributors

0xch4z avatar abemassry avatar alioso avatar andystevensname avatar asauber avatar bbiggerr avatar briansteffens avatar ddevault avatar displague avatar dorthu avatar eatonphil avatar hzoppetti avatar jamesottinger avatar jddocs avatar jskobos avatar lbgarber avatar leslitagordita avatar lgarber-akamai avatar na3d avatar nmelehan avatar patthiel avatar richardmcintosh avatar rmcintosh avatar robertderose avatar sagesyr avatar stvnjacobs avatar vernholio avatar wildmanonline avatar yoshizzle avatar zliang-akamai avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

linode-api-docs's Issues

Add "Copy" text to all copy button images

Do not reply solely on the icons to explain what they do. We need to include a some form of helper text to all images.

This is one example in our documentation where we need to provide a "Copy" action text as part of the icon being displayed. In addition, once the action completes on the subsequent "check-mark" displayed a "Copied" message should appear under the "check-mark."

image

Fix Breadcrumbs

Currently, breadcrumbs are somewhat useless, only ever directing you to the group-level page and the current page.

This looks silly, and should not have the > /domains part:
screen shot 2018-01-02 at 11 08 57 am

This is not helpful, and should be more like /domains > /:id > /clone:
screen shot 2018-01-02 at 11 08 52 am

Legacy API lifecycle.

Would it be possible to know or add the legacy (v3) API lifecycle (end of support date)?
I know new stuff should use the new API but we certainly have existing tools that use the legacy API and it would be good to know how long we have to switch everything over to the new API.

Use overflow: auto instead of overflow: scroll

Using overflow: scroll always displays a scrollbar on many browsers even if there is not enough content to scroll (Mac browsers mostly hide the scrollbar when it's needed because that's the UI you normally want). On all browsers you can simply set overflow: auto instead and it will only display the scrollbar if scrolling needs to happen.

There are two locations in particular where this makes the UI look awks:

On Chrome on Linux this looks like this:

2018-01-04-103803_1718x1438_scrot

When I swap out overflow: scroll for overflow: auto it looks like this:

2018-01-04-104036_1718x1438_scrot

I'd make a PR but there is no documented contribution guidelines for this new repo. (See #36.)

Clickable Anchors on Request Methods

"GET", "POST", "PUT", and "DELETE" sections of pages should have a clickable anchor that allows easy linking to that specific header, and modifies the page URL to reflect that position on the page.

Licensing

Hi!

I'm trying to make Linode a first class target for Guix deploy and as a prerequisite I need to package the CLI tool.
The problem is that it tries to download the OpenAPI YAML file at build time, which is explicitly not supported in Guix because it breaks reproducibility. I put it in a separate package, but since it is regularly updated, the checksum always breaks and we always have to update it.

We could use this git repo as the package source, then we could refer to old version. If using an old build fails, a user can always use a package transformation to use the latest one.

This would solve our problem, but we can't package this repo unless it has an open source license.

My question is, could you add such a license, so we could support Linode deployments better?

Here is the related issue on Guix's bugtracker.

issues in openapi spec

a couple of issues in the openapi spec file v.4.80.0 .. thought you might like to have a second look:

oauth2 scopes used without declaration in securitySchemes section:
object_storage:read_only
firewall:read_only
object_storage:read_write
maintenance:read_only
firewall:read_write
firewalls:read_only

and, scope called "events:read_only" controlling POST, looks like a typo?

- events:read_only

Java/Ruby client gen

Hey Linode Team,

I'm trying to generate client based on the openapi spec in this repo, but cli says that spec is invalid (tried java, ruby).

openapi-generator generate -i openapi.yaml -g java -o ./gen
Exception in thread "main" org.openapitools.codegen.SpecValidationException: There were issues with the specification. The option can be disabled via validateSpec (Maven/Gradle) or --skip-validate-spec (CLI).
 | Error count: 30, Warning count: 2
Errors:
	-attribute components.schemas.DatabasePostgreSQL.status is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQL.updated is not of type `schema`
	-attribute components.schemas.SecurityQuestionsPost.response is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.replication_commit_type is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.cluster_size is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.region is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.replication_type is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.count is not of type `schema`
	-attribute components.schemas.LinodeRequest.authorized_users is not of type `schema`
	-attribute components.schemas.LinodeRequest.stackscript_id is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.ssl_connection is not of type `schema`
	-attribute components.schemas.DiskRequest.filesystem is not of type `schema`
	-attribute components.schemas.LinodeRequest.stackscript_data is not of type `schema`
	-attribute components.schemas.LinodeRequest.image is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQL.created is not of type `schema`
	-attribute components.schemas.DatabaseMySQL.hosts is not of type `schema`
	-attribute components.schemas.DatabaseMongoDBRequest.storage_engine is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.allow_list is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.items is not of type `schema`
	-attribute components.schemas.DatabaseMongoDBRequest.compression_type is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.tags is not of type `schema`
	-attribute components.schemas.DiskRequest.label is not of type `schema`
	-attribute components.schemas.Volume.id is not of type `schema`
	-attribute components.schemas.SecurityQuestionsPost.question is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.encrypted is not of type `schema`
	-attribute components.schemas.LinodeRequest.authorized_keys is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.type is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQL.updates is not of type `schema`
	-attribute components.schemas.DatabaseMongoDBRequest.replica_set is not of type `schema`
	-attribute components.schemas.LinodeRequest.root_pass is not of type `schema`
Warnings:
	-attribute components.schemas.DatabasePostgreSQL.status is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQL.updated is not of type `schema`
	-attribute components.schemas.SecurityQuestionsPost.response is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.replication_commit_type is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.cluster_size is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.region is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.replication_type is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.count is not of type `schema`
	-attribute components.schemas.LinodeRequest.authorized_users is not of type `schema`
	-attribute components.schemas.LinodeRequest.stackscript_id is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.ssl_connection is not of type `schema`
	-attribute components.schemas.DiskRequest.filesystem is not of type `schema`
	-attribute components.schemas.LinodeRequest.stackscript_data is not of type `schema`
	-attribute components.schemas.LinodeRequest.image is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQL.created is not of type `schema`
	-attribute components.schemas.DatabaseMySQL.hosts is not of type `schema`
	-attribute components.schemas.DatabaseMongoDBRequest.storage_engine is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.allow_list is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.items is not of type `schema`
	-attribute components.schemas.DatabaseMongoDBRequest.compression_type is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.tags is not of type `schema`
	-attribute components.schemas.DiskRequest.label is not of type `schema`
	-attribute components.schemas.Volume.id is not of type `schema`
	-attribute components.schemas.SecurityQuestionsPost.question is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQLRequest.encrypted is not of type `schema`
	-attribute components.schemas.LinodeRequest.authorized_keys is not of type `schema`
	-attribute components.schemas.LKENodePoolRequestBody.type is not of type `schema`
	-attribute components.schemas.DatabasePostgreSQL.updates is not of type `schema`
	-attribute components.schemas.DatabaseMongoDBRequest.replica_set is not of type `schema`
	-attribute components.schemas.LinodeRequest.root_pass is not of type `schema`

	at org.openapitools.codegen.config.CodegenConfigurator.toContext(CodegenConfigurator.java:604)
	at org.openapitools.codegen.config.CodegenConfigurator.toClientOptInput(CodegenConfigurator.java:631)
	at org.openapitools.codegen.cmd.Generate.execute(Generate.java:457)
	at org.openapitools.codegen.cmd.OpenApiGeneratorCommand.run(OpenApiGeneratorCommand.java:32)
	at org.openapitools.codegen.OpenAPIGenerator.main(OpenAPIGenerator.java:66)

If I disable spec validation, if fails with NPE:

openapi-generator generate -i openapi.yaml -g java -o ./gen --skip-validate-spec

Output: https://gist.github.com/pbespechnyi/fe1df599ae6b8b732a1b6bf48fcbba6a

Specification Errors Prevent Parsing

Hi, I'm trying to use this specification (as well as the one on the website) and there are errors in it. This prevents it from being parsed by various tools.

  • example: {'survey_link': https://alinktothesurvey.com'} - missing single quote (after fixing manually I get the next errors)
  • in https://editor.swagger.io/ I get errors at lines 4432 and 18389, at the pattern property (after fixing manually I get the next errors)
  • When parsing it in .Net (https://github.com/microsoft/OpenAPI.NET) I get the following errors:
    • The reference string '/components/schemas/EntityTransfer/properties/entities' has invalid format.
    • The reference string '/components/schemas/PaginationEnvelope/properties/page' has invalid format.
    • The reference string '/components/schemas/PaginationEnvelope/properties/pages' has invalid format.
    • The reference string '/components/schemas/PaginationEnvelope/properties/results' has invalid format.

I just tried the same tools with the digital ocean yaml specification and it's parsed just fine.

It's a shame that I can't use this specification in .net. Could you fix the errors?

Thank you!

Request for contribution guidelines

The major question is: which branch do I make a PR against? And by extension, what is the release model? Any other info would probably also be useful for anyone interested in contributing.

Buggy active links

When you go from the introduction to Linodes, Introduction stays highlighted. When you go from Linodes back to Introduction, Linodes stays expanded and highlighted.

screen shot 2018-02-01 at 4 39 27 pm

screen shot 2018-02-01 at 4 39 33 pm

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.