diff --git a/docs/dev/api_quickstart.md b/docs/dev/api_quickstart.md new file mode 100644 index 00000000..7b33a1ab --- /dev/null +++ b/docs/dev/api_quickstart.md @@ -0,0 +1,73 @@ +# API Quick Start + + +The preview of the Validation Service API is available at `https://dev.validate.buildingsmart.org/api`. + +## Documentation + +Auto-generated documentation is available in both +[Swagger](https://dev.validate.buildingsmart.org/api/swagger-ui) +and +[Redocly](https://dev.validate.buildingsmart.org/api/redoc) +formats. + +## Auth token + +You will need an Authentication token before making calls to the API, +which can be obtained by emailing [validate@buildingsmart.org](mailto:validate@buildingsmart.org). + +You can use this token either as a Bearer token or use it as the password in combination with your username/email for basic authentication. + +## Example usage + +1. Sample to show difference between Token vs. Basic authentication + + ``` shell + curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Token ' + ``` + + -or- + + ```shell + curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Basic ' + ``` + + where `` is the Base64-encoded email and token as password, separated by a colon, eg. base64(johndoe@gmail.com:abcdefgh12345) + +2. Submit a POST request to the `/validationrequest` endpoint to initiate a new Validation Request (requires a file name and the file contents): + + ```shell + curl -X POST --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' \ + + --header 'Authorization: Token ' \ + + --form 'file_name="valid_file.ifc"' \ + + --form 'file=@"/.../buildingSMART/sample_files/valid_file.ifc"' + ``` + + It will return a JSON object that includes the id (public_id) you can use for future GET requests. + +3. Fetch details of a single ValidationRequest via a GET request to the `/validationrequest` endpoint + + ```shell + curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/r767775526' --header 'Authorization: Token ' + ``` + +4. Fetch details of all ValidationRequests via a GET request to the `/validationrequest` endpoint + + ```shell + curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationrequest/' --header 'Authorization: Token ' + ``` + +5. Fetch all ValidationTasks for two ValidationRequests via a GET request to the `/validationtask` endpoint + + ```shell + curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationtask/?request_public_id=r75257132,r383446691' --header 'Authorization: Token ' + ``` + +6. Fetch all the outcomes of a single ValidationRequest via a GET request to the `/validationoutcome` endpoint + + ```shell + curl -X GET --location 'https://dev.validate.buildingsmart.org/api/validationoutcome/?request_public_id=r75257132' --header 'Authorization: Token ' + ``` diff --git a/docs/dev/ifc_gherkin_rules_readme.md b/docs/dev/ifc_gherkin_rules_readme.md index b4f42f09..244ed755 100644 --- a/docs/dev/ifc_gherkin_rules_readme.md +++ b/docs/dev/ifc_gherkin_rules_readme.md @@ -9,7 +9,7 @@ An overview of the implemented rules and python step implementation functions is ## Making changes -The rules developed in this repository follow the general ideas of Gherkin and its python implementation behave. +The rules developed in this repository follow the general ideas of Gherkin and its python implementation [behave](https://behave.readthedocs.io/en/stable/). This means there are human-readable definitions of rules and Python implementations. diff --git a/docs/dev/index.md b/docs/dev/index.md index 3e3e42b5..c0c01d41 100644 --- a/docs/dev/index.md +++ b/docs/dev/index.md @@ -4,6 +4,10 @@ :heading-offset: 1 ``` +```{include} api_quickstart.md +:heading-offset: 1 +``` + ```{include} ifc_gherkin_rules_readme.md :heading-offset: 1 ``` diff --git a/docs/ref/index.md b/docs/ref/index.md index 9c4e7b25..35ebc2d7 100644 --- a/docs/ref/index.md +++ b/docs/ref/index.md @@ -35,3 +35,8 @@ The responses to these inquiries are provided here for the benefit of the entire :heading-offset: 1 :relative-images: ``` + +```{include} ./normative-rules/BRP003.md +:heading-offset: 1 +:relative-images: +``` diff --git a/docs/ref/normative-rules/BRP003.md b/docs/ref/normative-rules/BRP003.md new file mode 100644 index 00000000..d6c2748b --- /dev/null +++ b/docs/ref/normative-rules/BRP003.md @@ -0,0 +1,13 @@ +# BRP003 + +This rule confirms that geometric faces indicated as being planar +do actually lie on the same plane. + +## Approach + +1. Derive the plane from the outer boundary; uses Newell’s method for the normal and compute d from the average of the input points. +2. Validate outer and inner boundaries by projecting their points onto that plane and checking that each projection distance is within the representation context precision. + +```{note} +All calculations are performed in 128-bit floating point. +```