common-raml-fragment

Common Fragment RAML

A template with reusable fragments to boost your projects!

About The Project

The Common RAML Fragment project aims to simplify the development of RAML (RESTful API Modeling Language) specifications by following predefined standards. It provides a set of reusable fragments that cover key aspects of RAML specifications, allowing you to create consistent and standardized specifications for your APIs.

Project Contents

The project offers a variety of key resources to assist in the development of your RAML specifications:

Resource Types

1. System Layer: This resource type is designed for the system layer and includes security measures such as clientEnforcement, as well as common headers shared across layers.
2. Process Layer: Intended for the processing layer, this resource type also includes clientEnforcement security measures and common headers across layers.
3. Experience Layer: For the experience layer, this resource type implements oAuth2.0 security measures suitable for specific authentication scenarios.
4. Generic: This resource type provides a generic approach for other cases where none of the previous types directly apply.

Standard Structures

• Default Error Structure: Defines the main error types that can be returned by the API using APIkit policies.
• Common Headers Across Layers: Includes headers that are shared across multiple layers of your API, ensuring consistency and compliance.
• Query Parameters for Pagination and Sorting: Defines common parameters used for pagination and sorting of results in your API calls.
• Response Headers for Rate Limit Policies: Defines response headers used in conjunction with rate-limiting policies.
• Request Structures: Includes request structures for common formats such as JSON, XML, and form-data.
• Response Structures: Defines response structures with HTTP status codes 200, 201, 202, and 204, for formats such as JSON and XML.

The Common RAML Fragment project streamlines the process of creating high-quality RAML specifications, saving time and ensuring compliance with established standards. Use these reusable resources to create more consistent and well-documented APIs.

(back to top)

Usage Instructions

(optional step) Import the following security project to use files (experience-resourcetypes.raml, process-resourcetypes.raml and system-resourcetypes.raml), these files are not mandatory, they are to show that it is possible to customize the fragment accordingly with the layer that is using the fragment with security policies. If you do not import the security fragment, remove the mentioned files.

1. Create a new RAML Fragment project in Design Centre named: "Common RAML Fragments"
2. Go to your Design Centre Project and choose "Import", then select the ZIP.
3. Ensure you set the root RAML as the one which has been imported.
4. Publish this asset to Exchange.
5. This asset can now be imported into any new API Specification Design Centre project.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Acknowledgments

Used as the basis for creating this template.

• Getting Started With RAML 1.0
• 3 types of API fragments design strategies
• Eliminate Redundancies in RAML with Resource Types and Traits
• RAML Version 1.0: RESTful API Modeling Language

(back to top)