Code Monkey home page Code Monkey logo

sap-docs / api-style-guide Goto Github PK

View Code? Open in Web Editor NEW
4.0 4.0 0.0 4.34 MB

Markdown source for the SAP API Style Guide. Enables feedback and contributions to improve the documentation.

Home Page: https://help.sap.com/products/SNG_4_APIDOC/53e39c8b7c924c28a2575be50bc09786/01e4b09a0bb24235b3618deb0618e1af.html?version=PUBLIC

License: Creative Commons Attribution 4.0 International

documentation sap source-in-ditacms open-documentation-initiative

api-style-guide's Introduction

REUSE status

Contributions to SAP API Style Guide

Found a mistake in our documentation? Always wanted to add a step in one of our procedures that could save many others much time? Then you're at the right place! All contributions made to the Markdown files in the docs directory are reviewed, and if deemed valuable be added to our official documentation on SAP Help Portal. The easiest way is to start there, and choose Edit to find the right Markdown file to contribute to.

Requirements

For contributions, it's required that you have a GitHub account. For more information, see Signing up for a new GitHub account in the GitHub documentation.

Contributing

We recommend using the SAP API Style Guide on SAP Help Portal as a starting point for contributions:

  1. Open the SAP API Style Guide.
  2. You can either:
    • Choose Edit to suggest a change for the current page you see in the Help Portal viewer, or
    • Choose Feedback to open a GitHub issue in this repository.

If you only make a small contribution, that's the quickest way to propose a change. For larger contributions, we recommend forking this repository to work locally. The filenames in the docs directory are created based on the title of the page on SAP Help Portal.

More information: Contribution Guidelines

Code of Conduct

Adhere to the SAP Open Source Code of Conduct to ensure a welcoming and open culture for everyone involved in contributions to SAP documentation.

Licensing

See our LICENSE for copyright and license information.

api-style-guide's People

Contributors

ditaccms-bot avatar ospo-bot[bot] avatar qmacro avatar

Stargazers

 avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

api-style-guide's Issues

"REST and OData API Documentation" - system query options and OData service definition

In the About OData APIs section there's a table showing "what you can query", with the first column headed "Query". Might it be worth being more accurate here and using "System Query Option" instead, which is what they are? In this context also, $count is both a system query option, and also used as suffix (also in OData V2).

In addition, in the "OData Service Types and Documentation Requirements" section, the term "OData service" is used to refer to both producers and consumers of OData, err, services. "OData service" is a well-known term and I would suggest that it is confusing to refer to the consumer of an OData service, as an OData service. Perhaps something like "OData producers & consumers and documentation requirements" as a heading might help, with a similar modification for the content of this section?

"REST and OData API Documentation" - missing constraint (HATEOAS) and RMM

In this style guide the About REST APIs section talks about how an individual REST API is defined, listing various aspects. A fundamental aspect of REST, namely HATEOAS, is missing from the list. While HATEOAS is a constraint normally found only in APIs that have attained RMM level 3 and many pragmatic RESTful APIs exist without implementing that constraint, don't you think that we should at least mention the Richardson Maturity Model and include a fundamental aspect of REST in this list, rather than exclude it (see https://www.youtube.com/watch?v=bhn-Dl87SDE for background)?

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.