RMsis APIs (GraphQL)
RMsis provides GraphQL API's on all major entities and relationships. You can use these API's to develop integrations between RMsis and other applications. This guide will help you to understand how to access and utilise these API's.
Availability
RMsis 1.8.9.4
- Stable version of RMsis API's have been released as part of RMsis 1.8.9.4.
- A preview of RMsis API's were released as part of RMsis 1.8.9.2.
Prerequisites
This section covers primary information needed to access RMsis API's
JIRA API Authentication
- RMsis API endpoint i.e.
<JIRA_BASE_URL>/rest/service/latest/rmsis/graphql
is part of RMsis plugin. - So, you will need to access JIRA authentication API to receive authentication token and subsequently you can access RMsis API endpoint.
- If you do not have prior knowledge of accessing API in JIRA, please visit JIRA Server platform REST API reference
GraphQL
- RMsis uses GraphQL as its API standard
- GraphQL is query language for API's created by Facebook.
- You can learn more about GraphQL via specification http://facebook.github.io/graphql/ or example implementation https://github.com/facebook/graphql
- Some more getting started articles,
Resources
This section covers information about resources available in RMsis API's.
There are two main kind of resources available in RMsis, entities and relationships.
Entity
- All distinct and independent resources in RMsis are called entity.
- As RMsis imports some of them from JIRA, we can classify entities as internal and external.
- Internal Entities
- Requirement
- Planned
- Unplanned
- Release
- Test Case (Test Steps as its part)
- Test Run
- Requirement
- External Entity
- User
- Project
- In API's,
- For internal entities, all CRUD operations are provided, whereas,
- For external entities, only retrieve operation is provided (to get RMsis internal ID) and we encourage you to use JIRA Rest API's for other operations.
Relationship
- Links between entities is called relationship
- In API's, CRUD operations are provided for relationships
Structure
This section covers structure of API's provided in RMsis.
Request and Response Structure
RMsis follows GraphQL for request and response structure.
Request
Request to GraphQL endpoint can either be HTTP GET
or POST
method
- GET Method
- GraphQL operation query can be provided as a query parameter
<GrapQL_Endpoint>?query=<GraphQL_Operation_Query>
- Post Method
- GraphQL endpoint consumes
application/json
media type, and operation query is provided as request body Structure of this as follows
Grapql JSON Request Body{ query: "<GraphQL_Query>" //required variables: { //not required //Map of GraphQL variables } operationName: "<Name_of_Operation>" //not required }
- GraphQL endpoint consumes
Response
GraphQL returns media type application/json
as response. HTTP Code 200 or 400 is provided depending upon errors in response. Structure of this response is,
{ data: { //contains data response }, errors: [ //optional list of error while executing api //if there is any error in response, http status code will be 404. ] }
Operation Structure
As per GraphQL standard, API's in RMsis are divided in two operation structures, query and mutation types.
Query Type
API to retrieve any entity or relationships are part of query type. General structure for these API's are
- For entities
get<Singular_or_Plural_Entity_Name...>
search<Entity_Name...>
- For relationships
getTargetRelationshipEntities
getSourceRelationshipEntities
Mutation Type
API to create, update, or delete are part of mutation type. General structure for these API's are
- For entities
create<Entity_Name>
update<Entity_Name>
delete<Entity_Name>
- For relationships
createRelationship
deleteRelationship
More information about Structure of API's can be obtained from GraphQL Schema file.
Permissions
Permissions granted to users are same as the ones configured for a specific user.
API Playground
RMsis provides GraphiQL Playground (https://github.com/graphql/graphiql) build along side RMsis plugin for API documentation and testing API calls against your system. It can be accessed from your JIRA Menu Bar >> RMsis >> API Playground (<Jira_base_url>/secure/ApiPlayground.jspa
). A view of the GraphiQL user interface is presented below:
Samples
Few samples based on RMsis GraphQL,
Application Samples
Here are links to some applications created using RMsis GraphQL,
- https://bitbucket.org/optimizory-dev/rmsis-api-widgets
- Export RMsis data to a Word document
- Export RMsis data to an Excel document
Sample Request and Response
This section contains request and response samples based on current RMsis GraphQL implementation.
Information | Request Query | Response Code | Response JSON |
---|---|---|---|
Fetch list of Priority in system | 200 | ||
Fetch list of Users available in RMsis | 200 | ||
Fetch single requirement by ID | 200 | ||
Fetch requirement by ID | 404 | ||
Create planned requirement | 200 | ||
Delete Test Case | 200 | ||
Fetch linked artifacts of a requirement | 200 | ||
Fetch artifact externalID using RMsis ID | 200 |
Known Limitations
This section covers known limitations of current implementation.
- For external entities (i.e. JIRA entities), only internal and external ID is return
- we encourage you to use JIRA Rest API's for more information.
- Meta API's for custom fields are currently not available.
- API's for priviledged operations like version, commit, etc. are currently not available.
- Some operations requiring a UI context (like move etc.) are not yet provided.
- API's for configuration and administration are currently not available.