JIRA REST API（一）

1.REST插件模块是用来干什么的？

 

REST插件模块将服务和数据实体公开为REST API；REST模块基于JAX-RS,具体来说，它使用了Jersey。
REST API是通过URI路径来访问资源的，插件或脚本发出HTTP请求并解析响应。

 

请求方法是标准的HTTP方法，如GET，PUT，POST和DELETE；响应格式可以选择XML或JSON。

 

 

2.响应格式XML和JSON有什么不同吗？
  我们通过JAXB注解来实现Java类和XML/JSON的相互转化，常见的JAXB注解有@XmlRootElement、 @XmlElement、
@XmlAttribute、 @XmlAccessorType。

 

  默认情况下，JSON响应包括用JAXB注释显式注释的任何对象字段，而XML响应包括public字段和带有public getter的字段。

 

 

3.什么是JAXB？

 

  Java Architecture for XML Binding (JAXB)用于XML绑定的Java框架，将Java类映射为XML。

 

 

4.REST中访问资源的URI有什么书写格式吗？
格式：http://host.com:port/appName/rest/api-name/api-version/resource-name
例如：如果 自定义JIRA插件配置文件（atlassian-plugin.xml）中的rest标签为：

 

<rest key="helloWorldRest" path="/helloworld" version="1.0">
    <description>Provides hello world services.</description>
</rest>

那么 URI应为：
http://localhost:2990/jira/rest/helloworld/1.0/resource-name

【注意】

4.1 resource-name是rest类中注解声明的URI path，由此我们才知道哪个REST资源的哪个方法将被访问。

 

4.2 可以在resource name后指定接收response的类型，例如：resource-name.json/或resource-name.xml。

 

4.3 reource name类似于OOP中的对象，常用的资源名有"issue","user","attachment"。

 

 

5.在JIRA配置文件中，rest标签中有哪些值得注意的属性和子标签？
 5.1属性：版本version------这是REST API的版本，跟插件版本不一样。版本号遵循与OSGi版本相同的模式，
   即major.minor.micro.qualifier，其中major，minor和micro是整数。

 

 5.2子标签：包package------指明从哪里扫描资源，可以指定多个package，默认是扫描整个插件。

 

6.在创建rest资源类时，注解中有什么需要注意的？
 6.1 JAXB注解介绍：
  @Path()-----可以定义在包名、类名或方法名之上，对应的访问路径也不同。如果方法名上添加的是根路径，
          那么其他方法上不能再添加根路径。
  @GET------用在方法名之上，如果有多个方法名都添加了@GET注解，必须也要分别添加@Path()注解以区分开。
  @Produces------指定方法返回的内容类型，如果缺少该注解，则可以返回任意类型。
  @QueryParam------查询参数B定义在某个方法的参数A前，表示将一个查询参数B赋值给参数A，查询参数可以在               URI中指定。

 

   //例如：http://myhost.com:port/myapp/rest/api-name/api-version/resource-name?testParam=a
 
   Public Response getParam(@QueryParam("testParam")String testParam){}

  @PathParam------路径参数B定义在某个方法的参数A前，表示将访问路径中的参数B赋值给参数A。

 

//例如：http://myhost.com:port/myapp/rest/api-name/api-version/1234，
       // @Path("/{id}"),路径参数为1234，
        Public Response getParam(@PathParam("id")String id){}

  @AnonymousAllowed------用在方法名之上，允许匿名，不需要用户验证就可以调用方法；如果没有该注解，
  则需要和应用程序间建立会话或指定用户名/密码这样的参数。
  @XmlAccessorType------用在类名和枚举之上，用来控制字段或属性是否被默认序列化。